# Branch protection

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](https://forgejo.org/docs/v15.0/user/protection/).

## Add a rule

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.

## What a rule controls

### Push restrictions

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.

### Required reviews

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

A PR author cannot approve their own pull request.

### Required status checks

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.

:::note[CI minutes]
If your CI minutes are exhausted, runs fail and their statuses report as `failure`. This blocks any required status check until minutes are available again (through a top-up or the next billing cycle).
:::

### Other settings

| Setting | What it does |
|---|---|
| **Block if outdated** | Blocks merging when the PR branch is behind the base branch. |
| **Protected file patterns** | Semicolon-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 patterns** | The inverse: changes touching only these files are allowed even when the user cannot otherwise push. |
| **Enforce for admins** | Applies 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. |

## Always blocked

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.

## Manage with the MCP server

The [MCP server](/docs/mcp/) exposes branch protection management through the `branches` tool:

| Action | What it does |
|---|---|
| `list_protections` | List all rules for a repository |
| `get_protection` | Get a single rule by name |
| `create_protection` | Create a new rule |
| `update_protection` | Update an existing rule |
| `delete_protection` | Delete a rule |

The caller needs repository admin access. See the [tool reference](/docs/mcp/tools/#branches) 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.
