Sanctuary Branch Protection Setup — runbook

Purpose. This runbook walks the repository owner through the exact GitHub branch-protection settings required to make the test-baseline guard a hard merge gate, rather than a check that runs but can be ignored. Claude Code cannot set branch protection rules through code; this is a manual click-through Erik executes in the GitHub UI.

Prerequisites.

• Commits 26db204a (pre-commit hook) and 3035a47 (CI workflow) are on main.
• The test-baseline-guard workflow has run at least once on main and succeeded. If it has not, push an empty commit first so GitHub registers the check name.
• Erik has admin access to the eriknewton/sanctuary-framework repository.

Estimated time. 5 minutes.

Step 1 — Confirm the workflow has run at least once

Before you can name a status check as “required”, GitHub must have seen it complete at least once. Verify:

1. Go to https://github.com/eriknewton/sanctuary-framework/actions
2. Confirm there is at least one green Test Baseline Guard run on main. (It should show up automatically on the next push after commit 3035a47 lands.)
3. If no run is visible yet, push an empty commit to trigger it:

   git commit --allow-empty -m "ci: trigger test-baseline-guard registration"
   git push
   

4. Wait for the workflow to complete (≈ 1–2 minutes).

Do not proceed to step 2 until you have at least one successful test-baseline-guard run recorded in the Actions tab.

Step 2 — Open branch protection settings

1. Go to https://github.com/eriknewton/sanctuary-framework/settings/branches
2. Under Branch protection rules, click Add rule (or Edit if a rule for main already exists).

Step 3 — Configure the rule

Fill in the form with these exact settings. Items marked (required) are hard requirements from the hardening plan; items marked (recommended) are best-practice additions that make the guard harder to accidentally bypass.

Branch name pattern

• Set to main — exact branch name match.

Protect matching branches

• ☑ Require a pull request before merging (required)
  • ☑ Require approvals: 1 (or higher if you have collaborators)
  • ☑ Dismiss stale pull request approvals when new commits are pushed (recommended)
  • ☐ Require review from Code Owners — leave unchecked unless you have a CODEOWNERS file
  • ☐ Restrict who can dismiss pull request reviews — leave unchecked
• ☑ Require status checks to pass before merging (required)
  • ☑ Require branches to be up to date before merging (required) — forces every PR to rebase before merge, which ensures the status checks ran against the actual merge commit, not a stale one
  • In the Status checks that are required search box, add each of the following by name (each check must already have completed at least once for GitHub to find it):
    • test-baseline-guard (required) — the new CI job from commit 3035a47
    • test (22) (required) — existing Node 22 test job from ci.yml
    • test (24) (required) — existing Node 24 test job from ci.yml

  All three should appear in the required list. If test-baseline-guard does not show up, return to step 1 and push an empty commit to trigger a workflow run.

• ☑ Require conversation resolution before merging (recommended)
• ☑ Require signed commits (recommended) — raises the bar for agent and tooling commits
• ☐ Require linear history — leave unchecked; merge commits are fine for this repo
• ☐ Require deployments to succeed — leave unchecked; not applicable
• ☐ Lock branch — leave unchecked

Rules applied to everyone including administrators

• ☑ Do not allow bypassing the above settings (required)

  This is the critical box. Without it, repository administrators (including Erik) can force-push to main and bypass every other setting. With it, even the repo owner must go through a PR. The whole point of structural enforcement is to remove the “trust me, I’m careful” escape hatch.

• ☐ Allow force pushes — leave unchecked
• ☐ Allow deletions — leave unchecked

Step 4 — Save

Click Create (or Save changes). GitHub will confirm the rule is active.

Step 5 — Verify

Test the protection by attempting a direct push to main from a local clone with a trivial change:

echo "# verify branch protection" >> README.md
git add README.md
git commit -m "test: verify branch protection blocks direct push to main"
git push origin main

Expected result: GitHub rejects the push with an error like:

remote: error: GH006: Protected branch update failed for refs/heads/main.
remote: error: Changes must be made through a pull request.

If the push succeeds, branch protection is NOT active. Return to step 3 and verify the “Do not allow bypassing” checkbox is set.

After verifying rejection, revert the local change:

git reset --hard HEAD~1

Rollback

To temporarily relax the rule for an emergency:

1. Settings → Branches → main rule → Edit
2. Uncheck Do not allow bypassing (allows admin bypass)
3. Save
4. Perform the emergency action
5. Immediately re-check Do not allow bypassing and save again

Full removal (NOT recommended under any normal circumstance):

1. Settings → Branches → main rule → Delete

Document any rollback action in docs/audit/branch-protection-overrides.log (create on first use) with timestamp, actor, and one-sentence reason.

Why these exact settings

Related documents

• test-baseline-hardening-plan.md — the three-layer plan this runbook completes
• commit-4ac95830-postmortem.md — the trigger incident
• ../../CLAUDE.md — the written instruction layer (stopgap block, updated to reference structural enforcement)
• ../../.githooks/pre-commit — the local hook mirror
• ../../.github/workflows/test-baseline-guard.yml — the CI mirror

Runbook for Erik Newton. Sanctuary Framework. Apache-2.0.