Branch protection and rulesets

In MSBA-160 Priya turned on a single branch protection rule for main in trail-notes: changes had to arrive through a pull request with one approval, and editors were code owners for the chapter folders. It had worked all winter. At the March 8 session she showed what had gone wrong in the meantime. The new open-trail-report repository had no protection at all, and Malik had pushed a broken data file straight to main. The style guide had a protection rule that nobody remembered creating. And release tags in trailcheck had been deleted once by mistake. "Protection is one of those things you set up once and forget," Priya said. "The problem is the forgetting." This lesson covers the two tools GitHub provides, branch protection rules and rulesets, and how to choose between them.

Why protect branches at all

A branch is just a pointer, and anyone with write access can move it. Without protection, a single push can put untested or unreviewed changes on main, delete a branch, or rewrite its history with a force push, and on a busy team it can take a while to notice. Protection turns team agreements, such as "every change is reviewed" and "the build must pass", into rules GitHub enforces. It also makes those agreements visible to newcomers, who can see on the pull request page exactly which conditions are still unmet before the merge button becomes available.

Branch protection rules

A branch protection rule applies to the branches whose names match a pattern, such as main or release/*. An administrator creates it in the repository settings. Only one branch protection rule applies to any branch, and the most specific matching pattern wins. The settings fall into a few groups.

Two settings deserve a closer look. Dismiss stale approvals stops a common loophole: without it, someone can get an approval and then push more commits that nobody has reviewed. Do not allow bypassing the above settings (in older wording, include administrators) decides whether repository administrators must follow the rules. By default they can merge without meeting them, which is convenient in an emergency and risky the rest of the time.

Rulesets

Rulesets are the newer way to protect branches and tags. A ruleset is a named collection of rules with a target, an enforcement status and a bypass list. Rulesets cover the same ground as branch protection rules and add several things that branch protection cannot do.

First, several rulesets can apply to the same branch at once, and they layer: GitHub combines every rule from every matching ruleset and any branch protection rule, and where the same rule is set differently, the most restrictive version applies. Second, a ruleset has an enforcement status: Active, Disabled, and on GitHub Enterprise, Evaluate, which reports what would have been blocked without blocking it, so a team can test a rule before turning it on. Third, a ruleset has a bypass list naming the roles, teams or apps that may skip it, instead of the all-or-nothing administrator switch. Fourth, anyone with read access can see which rulesets apply, so a contributor does not have to guess why a push was refused. And fifth, rulesets can target tags as well as branches, and can include metadata rules, such as a pattern every commit message must match.

Rulesets and branch protection rules can be used together, which makes moving from one to the other gradual. GitHub recommends rulesets for new protections. Rulesets are available for public repositories on every plan and for private repositories on GitHub Pro, Team and Enterprise Cloud. Push rulesets, which can block pushes containing particular file paths, extensions or files above a size limit, are available for private and internal repositories on the paid organization plans. Organization rulesets target many repositories at once by name pattern or property, which is how an owner can make sure every repository has a protected main without visiting each one; check GitHub's plans page for which plans include them, because availability has changed as the feature has grown.

The rules available in a ruleset

The rules in a ruleset mirror the branch protection settings with a few additions. They include restricting creations, updates and deletions of matching branches; requiring linear history; requiring a pull request, with options for approvals, code-owner review, dismissing stale reviews and resolving conversations; requiring status checks; blocking force pushes; requiring signed commits; requiring deployments to succeed in named environments before merging; requiring code scanning results; and metadata restrictions on commit messages, author emails and branch names.

Rulesets can be exported and imported as JSON files, which lets a team keep a copy of its protection policy in a repository and apply the same policy elsewhere. A simplified export of the ruleset Priya wrote for the open trail-report repository looks like this.

{
  "name": "protect-main",
  "target": "branch",
  "enforcement": "active",
  "conditions": {
    "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] }
  },
  "bypass_actors": [
    { "actor_type": "Team", "bypass_mode": "pull_request" }
  ],
  "rules": [
    { "type": "deletion" },
    { "type": "non_fast_forward" },
    { "type": "pull_request",
      "parameters": { "required_approving_review_count": 1,
                      "dismiss_stale_reviews_on_push": true,
                      "require_code_owner_review": true,
                      "required_review_thread_resolution": true } },
    { "type": "required_status_checks",
      "parameters": { "required_status_checks": [ { "context": "validate-data" } ] } }
  ]
}

Reading it from top to bottom: the ruleset is called protect-main, protects branches, and is active. It targets the default branch. One team, the maintainers, may bypass it, but only through a pull request, so even a bypass leaves a record. The rules block deletion and force pushes, require a pull request with one approval that is dismissed by new commits and must come from a code owner, require review threads to be resolved, and require a status check called validate-data to pass. In the web interface the same settings are a page of check boxes; the JSON simply makes them easy to copy and compare.

Signed commits and the Verified badge

One rule in both tools, require signed commits, needs a little background. Git records an author name and email on every commit, but anyone can type any name and email into their Git configuration, so the author field alone proves nothing. A signed commit carries a cryptographic signature made with a key that belongs to the author, using GPG, SSH or S/MIME. When the matching public key is registered on the author's GitHub account, GitHub shows a Verified badge beside the commit. Commits made in the GitHub web interface are signed by GitHub automatically. With the rule turned on, unsigned commits cannot reach the protected branch.

For Tidewater, signed commits were a judgment call. They add a setup step for every contributor, and the editors already worked through pull requests that showed who had pushed what. Priya decided to require them only in open-trail-report, where outside contributors' work is merged and where a forged commit would be hardest to spot, and to encourage them elsewhere. Owen set up an SSH signing key in ten minutes by following GitHub's documentation, and checked that his next commit showed the badge.

Status checks: where they come from

A status check is a result that an automated system reports on a commit, shown as a green tick, a red cross or a yellow dot on the pull request. Most checks come from GitHub Actions workflows, which MSBA-160 introduced; others come from installed apps, such as a deployment preview service. A protection rule names the checks that must pass, by name. If a check is renamed in the workflow but not in the rule, pull requests wait forever for a check that never reports, which is one of the most common protection problems and the first thing to look at when a merge button stays grey for no visible reason.

Protecting tags and releases

Branches are not the only things worth protecting. A tag marks a release, and if a tag is moved or deleted, a reader of the release history can be misled about what was published. MSBA-160 used tags such as v2.0.0 for TrailCheck releases. A tag ruleset targeting v* with deletion and update restricted, and only the release managers on the bypass list, means a published tag can never be changed by accident. Priya added one to trailcheck the same afternoon, after confirming that the deleted tag from January could be recreated from the release notes.

Choosing protection for a small organization

With six regular contributors, Tidewater does not need elaborate rules. The team agreed on four patterns. Every repository has its default branch protected with a pull request, one approval and no force pushes or deletions. Repositories with automated checks, such as trailcheck and open-trail-report, also require those checks. Content repositories require code-owner review, so an editor approves every text change. Release tags are protected against deletion and updates. The old unnamed branch protection rule in style-guide was replaced by a ruleset with a clear name, and a short note in each repository's CONTRIBUTING file explains what the rules are and why.

Malik asked what happens in a real emergency, for example a safety notice that must go on TrailCheck within minutes. Priya's answer was that the protections are not the obstacle they look like: a one-line pull request can be opened, approved and merged in a couple of minutes by two people, and if only one person is available, the bypass list for trailcheck includes Priya and Rosa, whose bypasses are recorded. What the rules prevent is the quiet change nobody looked at, which is exactly the kind that causes trouble later.