Tier-3 install runbook — flipping branch protection on per-repo¶
| Field | Value |
|---|---|
| Status | Authored 2026-05-05 (Block 66C.2); not yet executed on any repo |
| Anchors | ADR 0109 trunk-based collaboration · ADR 1015 code-review discipline · docs/design/pr-governance.md |
| Companion | docs/operations/branch-protection-rules.md (rule-set spec) · ops/ci/branch-protection-readiness.sh (pre-flight check) |
This runbook is the end-to-end operator runbook for flipping Tier 3 of the code-review discipline on for a repository. ADR 1015 declares Tier 3 (PR review with CI gates) — this document is the operator's how-to for installing it.
§0 When to run this runbook¶
Per ADR 0109, branching adoption is per-repo with merge queue at >3 active contributors. Trigger conditions for running this runbook on a repo:
| Trigger | Action |
|---|---|
| Repo grows to 3 active contributors in the last 30 days | Run §1-§3 (basic branch protection); skip §4 (merge queue) |
| Repo grows to >3 active contributors in the last 30 days | Run §1-§4 in full |
| Repo is going public (OSS publication per Block 29) | Run §1-§3 even if <3 contributors — public repos must reject direct push |
| Sponsor / external reviewer asks for branch protection evidence | Run §1-§3 + document evidence in docs/compliance/ |
For repos that don't meet any trigger today: don't run this runbook. Tier 1 (block-completion self-review per ADR 1015) is in effect; that's the operative discipline.
§1 Pre-flight (before touching the GitHub UI)¶
§1.1 Run the readiness script¶
cd /path/to/repo
ops/ci/branch-protection-readiness.sh
Expected output:
=== Branch protection readiness — pre-flight check ===
PASS ci.yml (lint-shell + lint-yaml)
PASS compose-lint.yml
...
Branch protection readiness: 39 pass, 0 fail
STATUS: GREEN — safe to flip branch protection per docs/operations/tier-3-install-runbook.md
If RED: stop. The script prints which artifact is missing. Author it before proceeding. The most common reasons:
- A required CI workflow file is missing → author it (Block 66A pattern)
- The PR template doesn't include the ADR 1015 fields → re-extend it (Block 66B.1)
- CODEOWNERS doesn't cover security-sensitive paths → fix (Block 66B.2)
- No
block-*-completion-review.mdfiles → at least one Block must be released under ADR 1015 first
§1.2 Verify the workflows actually run on the repo¶
This step catches workflow-name typos before branch-protection rules require them. Open a no-op PR (e.g. fix a typo in a comment, or chore: trigger CI) and verify every workflow in the required-status-checks list of branch-protection-rules.md §1 actually fires:
gh pr create --title "chore: branch-protection pre-flight" --body "verifying CI fires" --draft
gh pr checks <PR-number>
Expected: every required check appears in the output, even if some are SKIPPED (path-triggered). If a check is missing entirely, fix the workflow's paths: filter or trigger pattern before proceeding.
§1.3 Verify pgp + DCO setup is current for all named contributors¶
Every active contributor needs a working GPG key and DCO sign-off configured. Branch protection will reject any contributor whose setup is broken.
# For each active contributor, verify their last commit is signed:
git log --show-signature -1 --author='<email>'
# Look for "Good signature from"
# Verify DCO sign-off:
git log -1 --pretty=%B --author='<email>' | grep "Signed-off-by:"
Per CONTRIBUTING.md §"Commits": every commit on main is signed; the DCO sign-off is required.
§2 Toggle branch protection (the actual flip)¶
§2.1 Open the GitHub branch protection settings¶
Settings → Branches → Branch protection rules → Add rule (or Edit if a rule already exists).
Branch name pattern: main
§2.2 Apply rule group A (author authenticity)¶
Per branch-protection-rules.md §1 rule group A:
- ☑ Require signed commits
- ☑ Require linear history
- ☑ Require a pull request before merging
- ☑ Required approving reviews: 1
- ☑ Dismiss stale pull request approvals when new commits are pushed
- ☑ Require review from Code Owners
- ☑ Require conversation resolution before merging
Save. Verify by attempting an unsigned direct push from a sandbox clone:
git -c commit.gpgsign=false commit --allow-empty -m "test unsigned"
git push origin main
# Expected output: rejected, "(unsigned commits are not allowed on this protected branch)"
# Or: rejected, "(only PRs can update this branch)"
§2.3 Apply rule group B (required CI status checks) ONE AT A TIME¶
This is the highest-risk step. GitHub matches required status checks by exact job name (not workflow file name); typos here silently cause the check to never block. Add them one at a time, verify the merge button blocks until each is green.
For each entry in branch-protection-rules.md §1 rule group B:
- Add it to "Status checks that are required."
- Save.
- Open the no-op PR from §1.2.
- Verify the merge button is blocked until that check is green.
- Verify the check name matches what's actually firing (the GitHub UI shows the firing check name; copy that exact string).
Also enable: ☑ Require branches to be up to date before merging (strict mode).
§2.4 Apply rule group C (administrators)¶
- ☑ Apply rules to administrators
- ☐ Allow force pushes (DO NOT enable)
- ☐ Allow deletions (DO NOT enable)
Save. Verify by attempting an admin direct push (if you have admin access on a sandbox account):
git push origin main
# Expected: rejected even with admin
§2.5 SKIP rule group D (merge queue)¶
Unless you're at the >3 active contributors threshold, leave merge queue OFF. If you ARE at the threshold, see §4 below.
§3 Post-flip verification¶
§3.1 Smoke test the full PR flow¶
Open a real (non-draft) PR with a small change. Walk through every gate manually:
- ✓ PR template renders correctly with the ADR 1015 fields
- ✓ CODEOWNERS auto-requests review
- ✓ All required CI checks fire
- ✓ Merge button is blocked until checks green + review approved
- ✓ Squash-merge produces a clean main-branch commit
- ✓ Track trailer (
[track: <name>]) is preserved through the squash
§3.2 Update the implementation-plan.md "Human / external actions register"¶
Add a row recording the date branch protection flipped on, the repo name, and the rule groups applied. Format per existing H-item entries.
§3.3 Update CONTRIBUTING.md if needed¶
If this is the first repo to flip Tier 3 on, update CONTRIBUTING.md §"Pull requests" to reflect that PRs are now required (not optional). If subsequent repos, no doc change needed.
§3.4 Notify active contributors¶
For active-contributor channels (Matrix room, Slack, etc.), post a one-line announcement:
Branch protection now active on
<repo>:main. Direct push is rejected; please use PRs. See docs/design/pr-governance.md for the full picture.
§4 Merge queue (only at >3 active contributors)¶
When the trigger fires (>3 active contributors per ADR 0109), enable the merge queue per branch-protection-rules.md §1 rule group D:
- ☑ Require merge queue
- Build concurrency: 5
- Maximum entries to merge: 5
- Maximum entries to build: 5
- Minimum entries to merge: 1
- Maximum minutes to wait for entries: 5
- ☑ Only merge non-failing pull requests
Verify with two simultaneous PRs:
- Open PR-A and PR-B with conflicting changes to the same file.
- Both pass CI individually.
- Both authors hit "merge."
- Verify GitHub puts them in the merge queue (visible at
Merge queuetab). - PR-A merges first; PR-B's speculative-merge build fails; PR-B is requeued behind PR-A's actual merge state.
§5 Rollback¶
If a rule causes operational pain after flipping:
- Do NOT loosen rules silently. Open an issue documenting the pain.
- Tune individual rules rather than disabling whole rule groups. The strict-mode "branches up to date" rule is the most common pain point during multi-PR weeks; it can be relaxed without dropping the other rules.
- Required-status-check name drift is the second most common: a workflow renames a job, the required-check rule silently doesn't match. Mitigation: re-run
branch-protection-readiness.shon a regular cadence (weekly cron candidate). - Never disable signed-commits. That's the load-bearing author-authenticity invariant.
- Document any rollback in implementation-plan.md "Human / external actions register" with date + reason.
§6 What this runbook does NOT cover¶
- The rule-set spec — see
branch-protection-rules.md. This runbook tells you when + how to toggle; that doc tells you what rules. - Cross-repo coordination — see ADR 0109 §"Cross-repo coordination". This runbook is per-repo.
- CODEOWNERS expansion — initial scaffold lives at
.github/CODEOWNERS; specific role/people expansion is tracked in implementation-plan.md "Human / external actions register" as H-items. - Tier-1 / Tier-2 review discipline — see
docs/design/code-review-process.md. Tier 3 is the PR-time install of an existing discipline; the discipline itself doesn't change at flip time. - Block 63C codex retrofit — five mechanical rules become CI gates per ADR 1014. When those land, add them to the required-status-checks list per §2.3.
- Block 40 supply-chain signing — cosign / SLSA L4 / Rekor wire to release tags, not PR. They're not in the per-PR required-status-checks list.
§7 Open questions¶
- Per-repo trigger automation. Today the >3 active contributors trigger is operator-judgment. Future: a
gh-active-contributorsscript that checks the trigger condition automatically and posts to a channel when it fires. - Cross-repo branch-protection consistency. When goat flips Tier 3 on but a sibling repo doesn't, contributors hit different friction in each repo. Open: do we batch flip all sibling repos at once, or accept asymmetry?
- Bypass policy. Default: no bypasses. Open: emergency response (offline-CA + LUKS-zeroize on-call) — bypass or always-via-policy-engine? Probably always-via-policy-engine; the bypass surface is itself a security risk.