Skip to content

Branch protection

Last updated:

Branch protection rules let you enforce guardrails on important branches. A rule can require pull request reviews before merging, mandate passing CI checks, restrict who may push directly, and more.

Branch protection is stock Forgejo. This page covers how it works on Codebahn and the options available. For the upstream reference, see the branch and tag protection documentation.

Go to your repository’s Settings > Branches and add a new rule. The rule name can be:

  • A branch name like main. Matched case-insensitively.
  • A glob pattern like release/* or release/**. Matched case-sensitively. * matches one path segment, ** crosses / separators.

When multiple rules match a branch, a plain name wins over a glob. Within the same kind, the rule created first wins. Rules never merge: only the first match applies.

By default, a new rule blocks all direct pushes. You can open it up:

  • No one (the default): all changes must come through pull requests.
  • Everyone with write access: anyone who can write to the repo can push directly.
  • Whitelist: only specified users, teams, or deploy keys can push directly.

Direct pushes bypass review and status check requirements. If you need those checks enforced, keep direct pushes restricted.

SettingWhat it does
Required approvalsNumber of approving reviews needed before a PR can merge. Set to 0 to require none.
Restrict approvals to whitelistOnly listed users and team members count as approvers. Without this, anyone with write access counts.
Dismiss stale approvalsWhen new commits are pushed to a PR, existing approvals are dismissed. The PR must be re-approved.
Ignore stale approvalsStale approvals stay visible but are not counted toward the required number.
Block on rejected reviewsA PR with an undismissed “request changes” review cannot merge.
Block on official review requestsA PR with pending review requests (including from CODEOWNERS) cannot merge until those reviewers respond.

A PR author cannot approve their own pull request.

When enabled, you specify one or more patterns that must match a passing status check on the PR’s head commit. Only success passes; pending, failure, and error all block merging.

Forgejo Actions jobs report statuses with the naming pattern workflow / job (event). For example, a job called test in a workflow called CI triggered by a pull request appears as CI / test (pull_request). Use this name (or a glob matching it) as your required status check pattern.

A pattern that matches no status is treated as pending, which blocks the merge.

SettingWhat it does
Block if outdatedBlocks merging when the PR branch is behind the base branch.
Protected file patternsSemicolon-separated globs. Changes to matching files cannot be pushed directly, even by whitelisted users. Patterns are case-insensitive. * does not cross / or ., so use ** for deeper paths.
Unprotected file patternsThe inverse: changes touching only these files are allowed even when the user cannot otherwise push.
Enforce for adminsApplies review, status check, and merge restrictions to repository admins. Without this, admins can force-merge a PR that has not met the requirements. Site admins can always force-merge.

Regardless of settings, a protected branch always blocks:

  • Force pushes: refused for every user, including admins and site admins.
  • Branch deletion: refused for everyone. The default branch is also protected from deletion even without a rule.

There is no setting to allow force pushes or deletion on a protected branch.

The MCP server exposes branch protection management through the branches tool:

ActionWhat it does
list_protectionsList all rules for a repository
get_protectionGet a single rule by name
create_protectionCreate a new rule
update_protectionUpdate an existing rule
delete_protectionDelete a rule

The caller needs repository admin access. See the tool reference for the full parameter list.

Note: the MCP tools cannot set apply_to_admins or ignore_stale_approvals. Use the web UI or API for those settings.