Branch Protection: main¶
🇧🇷 Versão em Português disponível: Leia em Português
Why this matters: Branch protection prevents force-pushes, requires passing CI checks before merge, enforces linear history, and ensures no one (not even admins) can bypass the pipeline. Without it, the agent orchestration pipeline (Iris → Themis → merge) is just a suggestion, not a guarantee.
Enable Protection via GitHub UI¶
- Go to your repo on github.com → Settings → Branches (sidebar).
- Click Add branch protection rule (or Add rule).
- In Branch name pattern, enter:
main - Enable the following checkboxes:
✅ Required Settings¶
| Setting | Checkbox label | Why |
|---|---|---|
| ✅ | Require a pull request before merging | All changes go through a PR reviewed by Themis/Iris |
| ✅ | Require approvals — set to 1 |
At least one reviewer must approve |
| ✅ | Dismiss stale pull request approvals when new commits are pushed | Re-review after changes |
| ✅ | Require status checks to pass before merging | Block merge if CI fails |
| ✅ | Require branches to be up to date | Prevents merge skew |
🔍 Required Status Checks¶
Add these exact check names (they match real workflow jobs; GitHub reports the
job id when a job has no name: override):
validatetest-suiteplugin-ts-coveragecommitlintsecurity-scanCodeQL
version-checkis not a check. That job was folded intovalidate. There is noPR Checksworkflow in this repository; do not addPR Checks / label-by-titleorPR Checks / recommend-version.Applying protection is a manual maintainer action. No workflow changes branch protection and an agent must not do it.
Tip: Type each name in the search box and select it. GitHub will auto-suggest matching check names once the workflow has run at least once on
main.
🔒 Additional Protections¶
| Setting | Checkbox label | Value |
|---|---|---|
| ✅ | Require linear history | — (on) — Prevents merge commits, keeps history clean |
| ✅ | Include administrators | — (on) — Even admins must follow the rules |
| ❌ | Allow force pushes | — (off) — Never allow force pushes |
| ❌ | Allow deletions | — (off) — Never allow branch deletion |
🚀 Apply Rule¶
Click Create (or Save changes).
Alternative: gh CLI¶
If you prefer the command line, use the GitHub CLI to apply the same settings:
gh api repos/:owner/:repo/branches/main/protection \
--method PUT \
--field required_status_checks='{
"strict": true,
"checks": [
{"context": "validate"},
{"context": "test-suite"},
{"context": "plugin-v2-ts-coverage"},
{"context": "commitlint"},
{"context": "security-scan"},
{"context": "CodeQL"}
]
}' \
--field enforce_admins=true \
--field required_pull_request_reviews='{
"required_approving_review_count": 1,
"dismiss_stale_reviews": true
}' \
--field required_linear_history=true \
--field allow_force_pushes=false \
--field allow_deletions=false
Note: Replace
:ownerwith your GitHub username or org (ils15) and:repowithpantheon-opencode. You needadminorwritepermissions on the repo to run this command. Run it only after every required check has passed onmain; see the pre-flight checklist below.
MANDATORY pre-flight checklist¶
If a required check never passes, every push to main is locked out, including
the release pipeline. Confirm all of the following before the PUT:
- [ ] (a) All six checks exist as workflow jobs:
validate,test-suite, andplugin-v2-ts-coverageinci.yml;commitlintincommit-lint.yml;security-scaninsecurity-scan.yml; and CodeQL analysis incodeql.yml. - [ ] (b) They all pass on current
main(or a PR), including the push run onmain. If any fails, fix the workflow first — never enable protection on a failing check. - [ ] (c) Only then apply the
PUT, and verify withgh api repos/ils15/pantheon-opencode/branches/main/protection.
Admin bypass¶
The command above sets enforce_admins=true. If the repository owner needs an
escape hatch to unblock the release pipeline, set it to false initially and
restore it after two stable releases:
gh api -X PATCH repos/ils15/pantheon-opencode/branches/main/protection \
-F enforce_admins=true
Grandfather policy¶
Commitlint is enforced from this point forward on all new commits (local
.husky/commit-msg hook plus the CI commitlint job). Commits before
2026-08 are grandfathered; they are never rewritten or retroactively linted.
git log -15 --format=%s | npx --no commitlint will list them as violations;
that output is expected. New commits must follow Conventional Commits.
Verification¶
After enabling protection, verify it's active:
gh api repos/ils15/pantheon-opencode/branches/main/protection --jq '.required_status_checks.checks[].context'
Expected output:
[
"validate",
"test-suite",
"plugin-v2-ts-coverage",
"commitlint",
"security-scan",
"CodeQL"
]
You can also check the GitHub UI: Settings → Branches → main rule shows
a green "Protection enabled" badge.
How This Enforces the Agent Pipeline¶
┌─────────────────────────────┐
│ User pushes to feature/ │
│ branch │
└──────────┬──────────────────┘
│
▼
┌─────────────────────────────┐
│ Iris opens Draft PR │
│ → validate, test-suite, │
│ plugin-v2-ts-coverage, │
│ commitlint, security-scan│
│ → CodeQL analysis │
└──────────┬──────────────────┘
│
▼
┌─────────────────────────────┐
│ All status checks pass? │
│ ─── NO ───→ Fix & re-push │
│ ─── YES ───↓ │
└──────────┬──────────────────┘
│
▼
┌─────────────────────────────┐
│ Themis reviews & approves │
└──────────┬──────────────────┘
│
▼
┌─────────────────────────────┐
│ User says "merge" │
│ → Iris merges (squash) │
│ → Linear history preserved │
└─────────────────────────────┘
Without branch protection, any of these steps can be skipped by a force-push
or a direct commit to main. Enable it once and never worry about it again.