gh-protect
gh-protect
Walk the user through building a GitHub repository ruleset and save it as JSON they can apply. Rulesets are GitHub's current mechanism for protecting refs and pushes (Settings → Rules → Rulesets), superseding classic branch protection. The output of this skill is a ruleset JSON file under .github/.rulesets/; applying it to the repo is a separate, explicitly-confirmed step — this skill never changes repo settings on its own.
The full rule catalogue, exact JSON parameter shapes, and complete example rulesets live in references/rules.md — read it before writing any rule you're not certain of, rather than guessing a parameter name.
Interview, then build
Ask only what's needed for the ruleset the user actually wants; don't march through every option. Suggest sensible defaults and let them override. Cover:
- Target type —
branch,tag, orpush:- branch — protect branches: require PRs, reviews, status checks, signed commits; block force-push/deletion.
- tag — protect tags: block deletion/update, enforce a tag-name pattern, require signatures.
- push — restrict what can be pushed repo-wide: file paths, extensions, size, path length. (No ref conditions — push rulesets apply to all pushes.)
- Name — kebab-case and sensical, used for both the filename and the ruleset's
name. Suggest something likeprotect-main,protect-release-tags, orblock-large-files. Validate it's kebab-case (^[a-z0-9]+(-[a-z0-9]+)*$); if the user offers something else, propose the kebab-case form. - Conditions (branch/tag only) — which refs it applies to: the default branch (
~DEFAULT_BRANCH), all (~ALL), or fnmatch patterns (refs/heads/main,refs/heads/release/*,refs/tags/v*). Support include and exclude lists. - Enforcement —
active(enforced),evaluate(dry-run, reports without blocking — organisation repos only), ordisabled. Defaultactive; suggestevaluatefirst when they want to trial a strict ruleset on an org repo. - Bypass list (optional) — who may bypass, and whether always or for pull requests only. Bypass actors are identified by numeric IDs that are specific to the repo/org (team, app, role, user), so don't invent them — either resolve them with
gh api(e.g.gh api /orgs/{org}/teams) or leave the bypass list empty and tell the user to add bypass actors in the UI after import. Default: no bypass (strictest). - Rules — pick from the catalogue in references/rules.md the ones that fit the target. For a typical
protect-main, a good default is: require a pull request (1 approval, dismiss stale reviews, require conversation resolution), block force pushes, block deletion, and — if they use CI — require status checks. Offer signed commits and linear history as stricter add-ons.