Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 36 ยท Administration and API

Branch Protection and Rulesets

Protect important branches and tags with branch protection rules and repository rulesets: required reviews, status checks, signed commits, merge queue and bypass lists.

Anyone with write access can normally push anything to any branch, including main. That is fine for a hobby project and risky for a team: one force-push can erase history, and one unreviewed change can break production. GitHub lets you attach rules to branches and tags so the safe path is also the easy path.

There are two systems. Branch protection rules are the older, per-branch-pattern settings. Rulesets are the newer, more flexible system that can target branches, tags and pushes, can be layered, tested in "evaluate" mode, and managed for a whole organization. New projects should prefer rulesets; the rules themselves are very similar.

The rules you will use most

Rule What it enforces
Require a pull request before merging No direct pushes; changes go through review
Required approvals A set number of approving reviews (for example 1 or 2)
Dismiss stale approvals New commits invalidate earlier approvals
Require review from Code Owners Owners from CODEOWNERS must approve
Require status checks to pass Named CI jobs must be green
Require branches to be up to date The branch must contain the latest base before merging
Require conversation resolution All review comments must be resolved
Require signed commits Commits must carry a verified signature
Require linear history Only squash or rebase merges, no merge commits
Require a merge queue Pull requests are tested together in order before landing
Block force pushes History of the branch cannot be rewritten
Restrict deletions The branch cannot be deleted
Require code scanning results Code scanning must pass

Required status checks are matched by job name. The name shown on the pull request (for example test (ubuntu-latest, 22)) must have run recently in the repository before you can select it. If a workflow is skipped by a paths filter, its required check stays "pending" forever; a common fix is a small always-running job that reports the result.

Creating a ruleset

In the repository: Settings -> Rules -> Rulesets -> New ruleset -> New branch ruleset.

  1. Name it (for example "Protect main") and set Enforcement status: Active, or Evaluate to log what would be blocked without blocking anyone.
  2. Bypass list: roles, teams or apps that may skip the rules (for example a release bot, or repository admins for emergencies). Keep it tiny; every bypass is a hole.
  3. Target branches: the default branch, all branches, or patterns such as release/*.
  4. Rules: tick the ones from the table.
  5. Save. Pull requests immediately show what is blocking the merge button.

You can create tag rulesets (for example v*) so only the release team can create or delete version tags, and push rulesets that block pushes of large files, certain file paths or file extensions. Organization owners can apply a ruleset to many repositories at once by name or property, so one policy covers the whole company.

Start new rulesets in Evaluate mode. Read the Rule Insights page, see who would have been blocked, fix surprises, and only then switch to Active.

How merges interact with the rules

On a pull request, GitHub offers three ways to merge, and you can limit which are allowed in repository settings:

  • Merge commit: keeps every commit and adds a merge commit.
  • Squash and merge: combines all commits into one on the base branch, tidy history.
  • Rebase and merge: replays commits on top of the base without a merge commit.

Auto-merge lets an author queue a pull request to merge itself the moment required reviews and checks pass. A merge queue goes further for busy repositories: it builds each pull request on top of the latest queue state and merges only if the combined result is green, which prevents "green alone, broken together" failures. Workflows used by the queue must listen to the merge_group event.

YAML
on:
  pull_request:
  merge_group:

A stand-in: evaluating a pull request against rules

The simulator below shows the idea of rule evaluation. The pull request object and the rule set are simplified stand-ins that we invented for this lesson; the real merge box considers many more details.

JS Stand-in: can this pull request merge? (simplified)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Practical advice

  • Protect the default branch and release branches at minimum; protect tags that trigger deployments.
  • Require at least one review, and a status check that runs your tests; add Code Owners review for sensitive paths such as .github/workflows/.
  • Prefer fine-grained roles to the "administrators can bypass" habit; if admins can ignore the rules, the rules protect less than you think.
  • Document the rules in CONTRIBUTING.md so contributors are not surprised by a blocked merge.
  • Remember that rules protect against mistakes, not against a determined attacker with admin rights; combine them with 2FA and audit logging.
  • On a solo project, "require a pull request" with zero approvals still gives you a CI gate and a tidy history.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main advantage of Evaluate mode in a ruleset?

    You can test a policy and fix surprises before enforcing it.
  2. 2. A required check stays 'pending' forever on a docs-only change. What is the likely cause?

    Skipped workflows do not report the required check; use an always-running job to report status.
  3. 3. Which merge option combines all commits of a pull request into one?

    Squash and merge produces a single commit on the base branch.
  4. 4. Why does a merge queue help busy repositories?

    It catches changes that pass alone but break when combined with others.

Summary

  • Rulesets (and older branch protection) enforce reviews, checks, signatures, linear history and more.
  • Keep the bypass list tiny; test new rules in Evaluate mode first.
  • Tag and push rulesets protect releases and block large or sensitive files.
  • Auto-merge and merge queues speed up safe merging; remember merge_group in workflows.

Next: The GitHub API, CLI and Webhooks