# Branch Protection

Minimal branch protection: require Pull Requests on `main`, disallow direct push. Only settable via web UI — the Forgejo API returns 403 on the branch protection endpoint.

## Web UI (per repo)

Navigate to `https://<forgejo>/<owner>/<repo>/settings/branches`

1. **Add Rule**
2. **Branch name pattern**: `main`
3. **Push**: select **Disable push** (the first option)
4. Leave everything else unticked/blank
5. Save

That's it. No whitelist, no signed commits, no status checks.

## Why not whitelist?

Whitelisting push users in Forgejo requires selecting from a dropdown that may not list all machine users. Instead: if an emergency direct push is ever needed, an admin temporarily unticks "Disable push", pushes, re-enables — two clicks, no permanent exception list to maintain.

## Pitfalls

- Forgejo's branch protection UI is verbose. Ignore everything except "Disable push." The other options (whitelist users, signed commits, status checks, protected file patterns) are advanced features — leave them all blank/unticked.
- The whitelist user dropdown may not contain all machine users. Don't fight the UI — use "Disable push" without whitelists. Emergency pushes are handled by the admin temporarily unchecking "Disable push," pushing, then re-enabling.
- Setting the default branch to the wrong branch during setup will confuse clones. Always set the default branch back to `main` after any branch settings page changes.
- If a branch has zero unique commits (everything merged into main), protect it anyway if it's a safety fallback (e.g., last known-good bootable ISO). Delete the branch + protection once a main-built artifact succeeds.
- **Default branch is separate from protection rules.** Changing the default branch (Settings → Repository → Default branch) does NOT add protection. Protection rules are under Settings → Branches → Add Rule.

## Verification

```sh
git clone git@<forgejo>:owner/repo.git test
cd test
git commit --allow-empty -m "test: probe"
git push origin main
# Expected: "remote rejected — pre-receive hook declined"
```