Protect branches and tags with rulesets#

A ruleset protects matching branches or tags: it can require pull requests, reviews and passing checks, or block deletion and force pushes. Repository admins manage rulesets under Settings → Rulesets. Organizations and teams can also define rulesets that apply to their repositories.

Create a ruleset#

1. Open Settings → Rulesets and choose New ruleset.
2. Under Basics, enter a name, choose the target (branches or tags), the enforcement and one or more patterns. * and ? are the only wildcards, for example main or release/*.
3. Under Rules, turn on the rules you want and fill in their settings (approval count, required check names and so on).
4. Under Bypass actors, optionally let an organization role or a user skip the rules, either always or only when merging pull requests. From the terminal or the API, an app installed in the organization can be a bypass actor too (--bypass app:amp); it bypasses only while it acts through that installation, never while the installation is paused or through another organization's installation.
5. Save.

Enforcement is one of:

• Active: the rules are enforced.
• Evaluate: the rules only produce warnings, so you can try them first.
• Disabled: the ruleset is kept but does nothing.

From the terminal, cafe repo ruleset create, edit, list and delete manage rulesets, and cafe repo ruleset effective main shows the rules that apply to a branch.

For example, allow only squash merges into staging:

To prohibit squash into production, use a separate ruleset targeting prod with allowed_strategies set to ["merge", "rebase", "fast-forward"]. The nonempty list accepts merge, squash, rebase and fast-forward. Policies apply to the target branch, not the source branch. Multiple active rulesets must all allow the selected strategy; evaluate-only rules warn and bypass actors can skip this constraint.

See which rules apply#

Effective rules, below the ruleset list, shows every ruleset that applies to the repository, including those inherited from the organization or a team. Inherited rulesets are edited where they are defined.

Anyone who can read the repository can read its rulesets, so the rulesets of a public repository are public. Only admins can change them, and only admins see a ruleset's bypass actors. The evaluated rules of a branch still tell every reader whether they themselves may bypass.

How rules affect pull requests#

Anyone can still open a pull request against a protected branch. Merging checks every active ruleset that matches the target branch:

• Require pull request: changes must arrive through a pull request with the required number of approvals. Each reviewer's latest approval or change request counts; the author's own review does not. Depending on the setting, a new push can make earlier approvals stale.
• Require status checks: each named check must pass on the exact commit being merged. With strict checks, the branch must also be up to date with the target. A check can be pinned to an app, so that only that app's check run satisfies it.
• Require linear history: merge commits are not allowed; use squash or rebase.
• Allowed merge strategies: only the listed strategies can merge into a matching target branch. The policy is checked again before publication, so changing a ruleset also applies to a queued merge.
• Code owners: each changed path needs approval from one of its owners in CODEOWNERS (looked up in the repository root, .gitcafe/, .github/, then docs/, from the target branch). The last matching pattern wins. Owners are users or organization teams with write access, or apps named by their slug (@amp) whose approval counts toward required reviews.
• Restrict pushes: only admins, or users with a branch role that allows it, can update the branch, including by merging.

The pull request's merge area lists any requirement that is not met.

Required signatures, required deployments and restricted file paths cannot be satisfied yet: they block matching merges unless a bypass applies.

How rules affect direct pushes#

Every pushed branch or tag update is checked. Creation, deletion and force-push restrictions apply to matching refs. Require pull request blocks direct pushes to matching branches. Rules that need checks or other evidence (status checks, linear history, signatures, deployments, file paths) also reject direct pushes to matching refs unless an always bypass applies. Evaluate-only rulesets never block a push. An allowed-merge-strategies rule alone does not restrict direct pushes; combine it with Require pull request to require changes to arrive through a PR.