GitHub Development Rulesets

Use Development JSON when creating or migrating a ruleset. It bundles the branch rules and role-based bypass policy, with an empty check list to fill from destination CI. Check-only updates preserve the destination's existing policy; migration adopts the bundled policy after reviewing its differences. Read Commands for selection, comparison, CI discovery, payload preparation and verification.

Workflow

1. Identify the destination and candidates. Record the selected host and repository. List rulesets with IDs, names, targets, enforcement and sources. Offer repository-owned branch rulesets as update candidates, including differently named ones. If several exist, ask which ID to use or whether to create a new ruleset. Show inherited rules as context for effective protection. Permission to explain or draft commands does not authorise changing GitHub settings.
2. Compare and choose the operation. Save the selected ruleset's complete current configuration and compare it with the bundled Development JSON. Compare name, target, enforcement, branch conditions, bypass actors, other rules and status-check flags; review required-check identities separately using destination CI. Require visible bypass_actors; missing data is not an empty bypass list. Show policy differences, accounting for ordering and API defaults. If policy matches, update its checks. If it differs, ask whether to migrate that ruleset to the bundled policy or create a new one. Honour an already explicit choice; record the chosen operation and ID before building a payload. For creation alongside existing rulesets, review their combined effective protection.
3. Establish CI identities. Use successful CI on the latest pushed revision, recording the SHA, run URLs and events. Fetch every page of commits/SHA/check-runs?per_page=100&filter=latest. Required contexts come from emitted .name, and source bindings from observed .app.id. Preserve case, punctuation, emoji, matrix suffixes and reusable-workflow prefixes. Inspect PR head/test-merge checks as applicable: a post-merge push-only check is not proof that PRs can satisfy it. A new repository needs real CI evidence before enforcement.
4. Select the requirements. Keep current valid destination requirements. Use clearly identified lint and build checks as the usual requirements when supported by CI evidence. Exclude path-detection, setup, publishing and notification helpers unless they genuinely validate the change. A missing run is not evidence that a requirement is obsolete. Remove a check only after confirming its retirement or replacement in workflow configuration and recent relevant runs. Record that evidence and the replacement, if any.
   • Treat new test requirements as optional. Unless the user has already decided, ask which test checks, if any, to require. Also ask about unfamiliar checks or checks whose purpose remains unclear after inspecting their workflow. Group these choices into one question with exact check names, a short explanation of each, and an option to leave them optional. Use the question tool when available, otherwise ask in chat. Record the choices with the CI evidence before preparing the payload.
   • Check workflow branch/path filters, event-specific job names and conditional dependencies. A skipped workflow can leave a requirement pending; a skipped job can pass without running validation. An aggregate gate must run and fail when its dependencies fail. If a merge queue applies, required checks must also run for merge_group.
   • Inspect legacy commit statuses when a name overlaps or a current requirement is absent from check runs. Do not invent an app ID from a status creator ID, copy a universal GitHub Actions ID, or silently change an existing source binding.
5. Review the payload. Project writable top-level API fields. Check-only updates preserve existing policy. Migration uses the bundled policy and carries forward valid existing required checks before applying the reviewed additions/removals. Creation fills the bundled empty list from destination CI. Show check changes and the complete configuration comparison; explicitly review every policy change for migration, including removed rules, renamed rulesets and changed bypass permissions. Prove the payload matches the chosen policy and check selection. Stop on ambiguous names/source bindings and investigate unsupported fields before proceeding.
6. Apply and verify. Once specifically authorised, re-read immediately before writing and stop if the reviewed destination changed. Use POST /repos/OWNER/REPO/rulesets for creation or PUT /repos/OWNER/REPO/rulesets/ID for an update or migration, with --input pointing to the reviewed payload. Re-read the result, compare the complete writable configuration, and check effective branch rules. Retain before/after snapshots, payload, CI evidence and the verification result. Report repository, operation, ruleset ID/URL, policy changes, added/retained/removed checks and any unverified PR coverage.

The installed gh ruleset --help owns available CLI subcommands. The verified command set has check, list and view; JSON import through the CLI uses the REST create endpoint. Check current help before claiming a native import command exists.