Audit GitHub branch protection with an agent SKILL.md
Cursor or Claude Code applies a SKILL.md to audit branch protection and rulesets: required reviews, status checks, force-push, admin bypass, and CODEOWNERS gaps — before policy drift merges.
A branch-protection SKILL.md in platform docs, a written gap list against your baseline, and tracked fixes for repos missing required checks or review counts.
- 1
Paste real gh api output for one repo
Redact tokens. Tune required check names against your workflow job outputs — mismatched names are the most common false pass.
- 2
Write the baseline appendix once
Minimum reviewers, checks, and CODEOWNERS paths belong in the skill file your org owns. Agents compare live settings to that appendix.
- 3
Schedule quarterly re-runs
Link the skill from platform runbooks. Protection drift often follows emergency admin merges.
The prompt to paste
Write SKILL.md for auditing GitHub branch protection and repository rulesets. Focus on merge gates and bypass paths — not general repo hygiene. Repository context: [org or repo names to audit — list placeholders] [default branch name, release branches if any] [required status checks by name from CI] [team baseline: min reviewers, CODEOWNERS required?, signed commits?, force-push policy] [rulesets vs classic branch protection — which the org uses] Audit context (paste when using): [repo list or single repo, link to settings export or gh api output redacted, recent incident if any] SKILL.md must include: 1. Purpose — branch protection is what keeps SKILL.md reviews and CI from being optional; silent bypass is a supply-chain control failure. 2. When to use — quarterly audit, new repo bootstrap, after admin role changes, or before SOC-style review. When not to use — fork-only personal sandboxes with no deploy keys. 3. Hard rules for findings: - Block (must fix before calling audit pass): default branch allows force push or deletion; no required pull request reviews on default branch; required checks missing names that CI actually publishes; admins bypass enabled without documented exception owner; empty CODEOWNERS on paths that deploy production [.github/workflows, infra, auth — per baseline]. - Warn: stale review dismissal disabled when team policy requires it; last-push approval not required for large teams; ruleset bypass actors too broad (entire org admin team); status checks set to "any source" when strict contexts required; branch protection only on main but releases cut from unprotected branch. - Note: number of required reviewers above baseline — informational unless policy defines exact count. 4. Audit steps the agent must execute: - For each repo: fetch protection on default branch and release branches [gh api commands as placeholders, no tokens in output]. - Record: required reviewers count, CODEOWNERS required flag, required status check names, enforce admins, allow force pushes, allow deletions, signed commits requirement. - Compare to baseline table in skill appendix [human fills baseline once]. - Cross-check CODEOWNERS file exists and covers critical paths; flag paths with recent churn but no owner. - List bypass actors on rulesets; flag service accounts with merge rights without MFA or offboarding owner. - Output gap report: repo — setting — expected — actual — severity. 5. Report template: executive summary counts, gap table, prioritized remediation tickets (title only, no auto-create unless asked). 6. Safe baseline section: example minimum for production repos — 1+ review, CI check matching main workflow, no force push, CODEOWNERS on workflows. 7. Two example prompts: audit one microservice repo vs org-wide sample of ten repos. 8. Pitfalls: trusting green CI badge without matching required check name, ignoring rulesets that override classic settings, auditing only main while tags deploy from unprotected branch, forgetting org-level allowlisted bots that count as reviews. 9. Done means: every Block has owner and target date or ticket id placeholder, baseline attached, no PAT or secret values in report, re-audit date suggested. Rules: - Do not paste GitHub tokens or webhook secrets; use [REDACTED] for actor names if sensitive. - Do not claim settings were fetched without showing command or export source placeholder. - Output only SKILL.md markdown.
Admin bypass plus missing CODEOWNERS on workflow paths recreates the secret-exfil merge path. The skill should Block that combination for production repos.
Sample case written by Hidden Logic Lab. Not affiliated with Cursor or Claude Code or GitHub.
More in Operations
Get new cases in your inbox
Weekly notes on new use cases and agent workflows. No product pitches.