Branch protection & reviews
Branch protection lets a repo admin guard specific branches —
typically main — from direct pushes, force-pushes, deletion,
and merges that don't meet the team's review/CI bar.
Configured at Repository → Settings → Branches.
Per-rule controls
A rule applies to one or more branches by name pattern (main,
release/*, etc.). Each rule can independently:
- Require pull request before merging — direct pushes to the branch are rejected. The only way in is a merged PR.
- Require N approvals — a PR can't merge without that many approvals from users with write access.
- Dismiss stale approvals on new commits — when the PR head moves, prior approvals are wiped.
- Require approval from someone other than the last pusher — the author of the most recent push to the PR can't be one of the approvers.
- Require conversation resolution — every line comment must be marked "Resolved" before merge.
- Require status checks — list of CI check names. The PR's head commit must report success on each before merge enables.
- Require status checks to be up-to-date — head must include the latest base commit before checks count.
- Restrict who can push (for non-PR pushes if PRs aren't required) — list of users/teams.
- Disallow force-pushes.
- Disallow deletions.
- Lock branch — read-only; no merges either. Used for archived release lines.
How reviews count
- Approvals from users with read-only access on the repo don't count.
- An approval is dismissed if the reviewer is removed from the repo.
- "Request changes" blocks merge until the same reviewer re-reviews (Approve or Comment) — a different reviewer's Approve does not lift the block.
Status checks
Status checks come from external CI runners (or, in the future, shithub's own runner). A check has:
- Context — the name (e.g.,
ci/lint,ci/test). - State —
pending,success,failure,error. - Description — short human text.
- Target URL — link to the run details.
The first time a context name appears on the repo, you can add it to the required-checks list. The PR's merge gate evaluates the head commit's most recent state per context.
Bypass
A repo admin can bypass branch protection for a single push (per-action; not a permanent setting) — useful for emergencies. The bypass is recorded in the audit log with the admin's id and the affected commits.
View source
| 1 | # Branch protection & reviews |
| 2 | |
| 3 | Branch protection lets a repo admin guard specific branches — |
| 4 | typically `main` — from direct pushes, force-pushes, deletion, |
| 5 | and merges that don't meet the team's review/CI bar. |
| 6 | |
| 7 | Configured at Repository → Settings → Branches. |
| 8 | |
| 9 | ## Per-rule controls |
| 10 | |
| 11 | A rule applies to one or more branches by name pattern (`main`, |
| 12 | `release/*`, etc.). Each rule can independently: |
| 13 | |
| 14 | - **Require pull request before merging** — direct pushes to the |
| 15 | branch are rejected. The only way in is a merged PR. |
| 16 | - **Require N approvals** — a PR can't merge without that many |
| 17 | approvals from users with write access. |
| 18 | - **Dismiss stale approvals on new commits** — when the PR head |
| 19 | moves, prior approvals are wiped. |
| 20 | - **Require approval from someone other than the last pusher** — |
| 21 | the author of the most recent push to the PR can't be one of |
| 22 | the approvers. |
| 23 | - **Require conversation resolution** — every line comment must |
| 24 | be marked "Resolved" before merge. |
| 25 | - **Require status checks** — list of CI check names. The PR's |
| 26 | head commit must report success on each before merge enables. |
| 27 | - **Require status checks to be up-to-date** — head must include |
| 28 | the latest base commit before checks count. |
| 29 | - **Restrict who can push** (for non-PR pushes if PRs aren't |
| 30 | required) — list of users/teams. |
| 31 | - **Disallow force-pushes**. |
| 32 | - **Disallow deletions**. |
| 33 | - **Lock branch** — read-only; no merges either. Used for |
| 34 | archived release lines. |
| 35 | |
| 36 | ## How reviews count |
| 37 | |
| 38 | - Approvals from users with **read-only** access on the repo |
| 39 | don't count. |
| 40 | - An approval is dismissed if the reviewer is removed from the |
| 41 | repo. |
| 42 | - "Request changes" blocks merge until the same reviewer |
| 43 | re-reviews (Approve or Comment) — a different reviewer's |
| 44 | Approve does not lift the block. |
| 45 | |
| 46 | ## Status checks |
| 47 | |
| 48 | Status checks come from external CI runners (or, in the future, |
| 49 | shithub's own runner). A check has: |
| 50 | |
| 51 | - **Context** — the name (e.g., `ci/lint`, `ci/test`). |
| 52 | - **State** — `pending`, `success`, `failure`, `error`. |
| 53 | - **Description** — short human text. |
| 54 | - **Target URL** — link to the run details. |
| 55 | |
| 56 | The first time a context name appears on the repo, you can add |
| 57 | it to the required-checks list. The PR's merge gate evaluates |
| 58 | the **head commit's most recent state per context**. |
| 59 | |
| 60 | ## Bypass |
| 61 | |
| 62 | A repo admin can bypass branch protection for a single push |
| 63 | (per-action; not a permanent setting) — useful for emergencies. |
| 64 | The bypass is recorded in the audit log with the admin's id and |
| 65 | the affected commits. |