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.
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.

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.

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.
• Require linear history: merge commits are not allowed; use squash or rebase.
• 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.
• 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.