Skip to main content
Security
Branch protection

Branch protection

Branch protection on fremforge follows the upstream Forgejo model: rules attach to branches by glob pattern, enforce review + status + history requirements, and block writes that violate them. fremforge adds org-wide defaults so the same posture applies to every repo without per-repo configuration drift.

Org defaults vs per-repo overrides

The Org → Repos page sets the rules that apply to every repo in the org. The defaults configure each repo’s main (or whatever your default branch is) on creation, and the daily backfill reconciler fills in any repo that has zero branch protection — it never overrides a repo admin’s existing settings. Repos that already have protection but have drifted weaker than the org default are surfaced by the drift detector as an alert rather than being auto-reverted (see below).

Per-repo overrides live on the repo settings page (/<org>/<repo>/settings/branches). Override only when the repo has a genuine policy exception — most teams set the org default once and never touch repo-level rules.

Settings that map directly to Forgejo

  • Require pull request reviews before merging. Set a minimum reviewer count (typically 1 or 2). Dismiss stale reviews on push to prevent rubber-stamps from surviving a force-amend.
  • Require status checks to pass before merging. Name the status contexts that must report success. The canonical fremforge-emitted checks are fremforge/dep-scan and fremforge/sast. See SAST for the full status-check catalog fremforge maintains.
  • Require signed commits. When on, unsigned commits on the protected branch are rejected at push. See Cosign for the commit-signing path with Sigstore short-lived certs.
  • Require linear history. When enabled, fremforge disables merge commits on the repo — merges are squash or rebase only, so the protected branch keeps a linear history.
  • Block force pushes. Refuses --force on the protected branch entirely.
  • Block branch deletion. A protected branch cannot be deleted — this is inherent to having a branch-protection rule attached, not a separate toggle. As long as the branch is protected, delete operations against it are refused.

Settings fremforge adds on top

  • Enforce protection on org owners/admins too. Forgejo exempts org owners from branch protection by default (matching GitHub/GitLab parity), so owners can bypass required reviews and status checks. fremforge exposes this as a per-tenant toggle on the Repos admin page — “Enforce protection on org owners/admins too” — which is off by default. Turn it on to make even owners subject to required reviews + status checks (Forgejo’s apply_to_admins).
  • Require CODEOWNERS review. Forgejo enforces CODEOWNERS automatically whenever a CODEOWNERS file exists in the repo and reviews are required — the matching code owners are added as required reviewers with no extra rule-level flag. The toggle on the Repos page is informational: it documents that the org expects CODEOWNERS coverage; there is no separate standalone control to switch on.
  • Status-check allowlist for fremforge-emitted checks. The contexts fremforge/dep-scan and fremforge/sast are the canonical names.
  • Drift detector. The daily defaults gap-scan also flags any repo whose branch protection is absent or weaker than the org default. This surfaces as a distinct admin Bell alert — “N repos with weakened branch protection” — that links to the Repos admin page. It is detect-and-alert only: fremforge does not auto-revert weakened settings, because a repo owner’s explicit settings win. Use the alert to decide whether to follow up with the repo owner.

Setting it up

  1. Open the Org → Repos page.
  2. Pick the branch glob (typically main or main, master, release/*).
  3. Set the toggles above. Save.
  4. The change is recorded in the audit log as repo-defaults.branch-protection.updated. A retroactive apply to existing zero-protection repos is logged as repo-defaults.branch-protection.retro-applied, and resetting the org defaults to the fremforge baseline is logged as repo-defaults.reset-baseline.

See also

  • Scorecard — branch protection drives the Branch-Protection OpenSSF score.
  • Authentication policy — the broader posture (signed commits, SSH transport, MFA).
  • Cosign — required-signed-commits implementation.
Image scanningLicense scanning