GitHub Branch Protection Rules: Why and How to Use Them

Published · Updated

GitHub branch protection prevents an important branch from relying only on team memory. A rule can require pull requests, approving reviews and passing status checks, while blocking force pushes or deletion. For new governance, also evaluate rulesets: GitHub presents them as an alternative that can layer multiple rules, expose rule evaluation more clearly and support explicit bypass actors.

Protection does not prove code is correct. It enforces a chosen path for changing a branch, so your reviews, tests and permissions become repeatable controls.

Branch protection versus rulesets

GitHub currently offers two related mechanisms:

  • A classic branch protection rule targets a branch name or pattern. Only one classic branch protection rule applies at a time, which can make overlapping patterns difficult to reason about.
  • A branch ruleset targets selected branches and can work alongside other rulesets. Rulesets can be created in an evaluate state before enforcement on plans that support that feature, and can grant bypass to selected roles, teams, apps or people according to repository ownership and plan.

Availability varies by repository visibility and GitHub plan. At the time of this update, classic protected branches and rulesets are available for public repositories on GitHub Free, while private-repository availability requires an eligible paid plan. Verify the current “Who can use this feature?” section in GitHub’s documentation for managing a branch protection rule and creating repository rulesets.

People need repository admin permission, or a custom role with permission to edit repository rules, to manage these controls.

A practical baseline for main

Start with the smallest policy your repository can actually satisfy:

  1. Require a pull request before merging.
  2. Require at least one approving review when a real independent reviewer is available.
  3. Dismiss stale approvals when new commits materially change the reviewed code.
  4. Require conversation resolution.
  5. Require the specific CI checks that reliably test every proposed change.
  6. Block force pushes and branch deletion.
  7. Apply the rules to administrators or prevent bypass unless an emergency path is explicitly needed.

Do not require a status check that has never run. GitHub only lets you select checks that have completed successfully in the repository during the recent period described by its current UI. A renamed or removed workflow can also leave pull requests waiting for a check that will never report. Treat required-check names as part of the repository’s configuration and update protection when CI changes.

Solo projects need judgment. Requiring an approving review that the only maintainer cannot supply can block all work. A solo maintainer can still require pull requests, conversation resolution and tests to create a reviewable change record, then add independent approval when collaborators join.

Configure a classic branch protection rule

GitHub’s interface changes over time, so use the current documentation as the source of truth. The present workflow is:

  1. Open the repository and select Settings. If Settings is absent, you probably lack the required permission.
  2. In the code and automation section, open Branches.
  3. Under branch protection rules, choose Add rule.
  4. Enter a specific branch name such as main, or a carefully reviewed pattern.
  5. Enable Require a pull request before merging, then choose the required approvals and whether stale approvals are dismissed.
  6. Enable Require status checks to pass before merging, select only dependable checks, and decide whether branches must be up to date before merging.
  7. Consider required conversation resolution, signed commits, linear history and deployment gates only when the project has a clear need and supporting workflow.
  8. Keep force pushes and deletion disabled unless there is a documented exception.
  9. Decide whether bypass is allowed, by whom, and for what emergency procedure.
  10. Save the rule.

GitHub’s managing a branch protection rule page contains the authoritative current labels and options.

Configure a ruleset instead

From repository Settings, open Rules, then Rulesets and create a new branch ruleset. Give it a descriptive name, choose enforcement status, define target branches, configure bypass actors deliberately, and add the rules the repository can satisfy.

Rulesets support controls such as restricting updates or deletions, blocking force pushes, requiring pull requests, requiring status checks, requiring signed commits and requiring successful deployments. Exact rules and availability differ by plan and repository type; consult Available rules for rulesets.

Prefer an explicit target for the default branch over a broad wildcard until you have tested how the pattern matches release and automation branches. Name the ruleset after its intent—for example, “Default branch review and CI”—rather than “Rule 1.”

Make bypass an auditable exception

Bypass can be necessary for recovering from a broken deployment or CI outage, but an unrestricted admin escape route weakens the policy. Decide before an incident:

  • which roles, teams or apps may bypass;
  • whether bypass is always allowed or pull-request-only where supported;
  • what incident qualifies;
  • who reviews the bypass afterward;
  • how the repository records the reason and corrective follow-up.

Never use force push as a routine way around a failing check. Fix the change or the check. If a credential entered history, rotate it first and follow GitHub’s sensitive-data removal procedure; branch protection is not secret remediation.

Test the rule instead of assuming

Create a harmless topic branch and pull request, then verify each expected control:

  • a direct push to the protected branch is rejected when it should be;
  • the PR cannot merge before required approval;
  • a failing required check blocks merging;
  • a new commit dismisses an approval if configured;
  • unresolved review conversations block merging if configured;
  • unauthorized users cannot bypass the rule;
  • deletion and force push are blocked;
  • the documented emergency actor can perform only the intended bypass.

Record the result in the repository’s contributor documentation. Re-test after changing CI workflow names, repository ownership, plans, merge methods or default branches.

Protection works with a clear workflow

Rules make more sense after the team shares the same vocabulary. Review repositories, branches and pull requests, then practise creating a repository and managing a PR. For a concrete first repository, use the guide to link a Spring Boot project to GitHub.

These governance habits are also relevant to the delivery and client-environment responsibilities in the Forward-Deployed Engineer program.