38 lines
2 KiB
Markdown
38 lines
2 KiB
Markdown
|
# 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"
|
||
|
|
```
|