GitHub rulesets and classic branch protection rules both protect a branch, and when both target the same branch, GitHub enforces every rule from both. Only one branch protection rule applies to a branch, but any number of rulesets can, and the strictest version of each rule wins. Rulesets also get a bypass list, a status you can switch off without deleting anything, and a page anyone with read access can open. I’d use a ruleset for anything new, and for old rules GitHub has a Convert to ruleset button.
What is the difference between GitHub rulesets and branch protection rules?
A ruleset is a named list of rules for branches or tags. A branch protection rule is the older setup, where one rule covers a branch name pattern. GitHub’s docs on rulesets list four differences.
- Several rulesets can apply to the same branch at the same time. Only one branch protection rule applies.
- You can change a ruleset’s enforcement status without deleting it.
- Anyone with read access can view a repository’s active rulesets, so developers see which rules apply without asking an admin.
- Rulesets can control commit metadata, such as commit messages and author emails.
Bypass works differently too. A classic rule exempts admins by default, and you turn on Do not allow bypassing the above settings to hold them to it. A ruleset exempts nobody until you add them to its bypass list.
How do rulesets and branch protection rules layer?
A ruleset has no priority. When several rulesets target a branch, GitHub combines their rules, and it adds any branch protection rule for that branch to the mix. If the same rule is set two ways, the most restrictive one applies. In GitHub’s own example, a ruleset that needs signed commits and three reviews, plus a protection rule that needs linear history and two reviews, gives a branch that needs signed commits, linear history, and three reviews.
So a branch can look unprotected under Settings, Branches and still block you. A push that breaks a ruleset fails with GH013, and our GH013 guide covers each rule line. To see everything that applies, add /rules to the repository URL.
Who can bypass a GitHub ruleset?
Only the actors on its bypass list. In the “Bypass list” section, click Add bypass and pick from repository admins, organization owners and enterprise owners, the maintain or write role (or custom roles based on write), teams, GitHub Apps, and Dependabot. Each entry starts as Always allow. Set it to For pull requests only and that actor can still merge past the rules, but only through a pull request, so there’s a record of it.
What do the Active, Evaluate and Disabled statuses do?
Active enforces the ruleset as soon as you create it. Disabled turns it off without deleting it. Evaluate, documented for GitHub Enterprise Cloud, enforces nothing but records which actions would have passed or failed, on the Rule Insights page under Settings, Rules, Insights. Use it to try a strict rule, such as a commit message pattern, before it blocks anyone.
Can I create rulesets for a whole organization?
Yes, on GitHub Team or GitHub Enterprise plans. An organization owner creates them under the organization’s Settings, Repository, Rulesets, and targets all repositories, repositories matching a name, repositories matching a custom property filter, or only selected repositories. They layer with each repository’s own rulesets and protection rules the same way. A repository can hold up to 75 rulesets, and an organization up to 75 organization-wide ones.
How do I convert branch protection rules to rulesets?
- Go to Settings, then Branches.
- Under “Branch protection rules”, click Convert to ruleset on the rule.
- Name the ruleset and read the “New behavior” section. One rule can become more than one ruleset.
- Click Create ruleset. Optionally select Delete branch protection rule once migration is done.
The new ruleset is Active right away. If you keep the old rule, both are enforced. Once the ruleset fully covers it, the old rule shows “This rule is fully covered by rulesets and can be safely deleted” with a Delete button, per the conversion docs.
A recommended ruleset to protect main
In the repository’s Settings, open Rulesets, click New ruleset, then New branch ruleset. Set enforcement to Active, add the default branch as a target, and turn on these available rules:
- Restrict deletions and Block force pushes. Both are on by default.
- Require a pull request before merging with one required approval, Dismiss stale pull request approvals when new commits are pushed, and Require approval of the most recent reviewable push. The last one has its own failure message, explained in our last pusher guide.
- Require status checks to pass before merging, naming your CI jobs.
Leave the bypass list empty, or add one admin role as For pull requests only so emergencies still go through a pull request. For the approval settings and the “at least 1 approving review is required” block, see our guide to required reviews. With pull requests as the only way in, you meet the rules in the merge box, and Pyor keeps that in an inspector beside the conversation while you review.
Frequently asked questions
Do rulesets replace branch protection rules?
Not automatically. Both can protect the same branch, and GitHub enforces every rule from both. Branches settings has a Convert to ruleset button for each classic rule, and you can delete the old rule once the ruleset covers it.
If a ruleset and a branch protection rule disagree, which one wins?
The stricter one. Rulesets have no priority. GitHub combines the rules from every ruleset and branch protection rule that targets the branch, and when the same rule is set two ways, the most restrictive version applies. Two required reviews in one and three in the other means three.
Can people without admin access see a ruleset?
Yes. Anyone with read access to a repository can view its active rulesets. Add /rules to the repository URL, or click the shield icon next to a branch under View all branches.