Protecting Your Main Branch With Required Checks

Branch protection turns "please don't merge failing code" into a rule the platform enforces for you.

CI only protects you if a failing pipeline actually blocks the merge. Branch protection rules with required status checks make that happen, so a red build cannot reach main. This lesson explains how the pieces fit together and how to set them up.

Why required checks matter

Running CI is pointless if anyone can merge while it is failing. Required status checks make specific CI jobs mandatory: GitHub will refuse to merge a pull request until those checks report success. This converts your test suite from a suggestion into a hard gate that protects the main branch automatically.

Common branch protection rules

• Require status checks to pass before merging (your CI jobs).
• Require branches to be up to date with main before merging.
• Require at least one approving review.
• Disallow force pushes and branch deletion on main.
• Require linear history to keep the log clean.

Connecting CI jobs to required checks

A status check is identified by the *job name* in your workflow. Once a workflow has run at least once on a pull request, that job name appears in the branch protection settings, where you select it as required. The match is by name, so renaming a job means re-selecting it in the protection rules.

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:            # <- this job name becomes a selectable required check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

A gotcha: checks that never run

If a required check is configured but the workflow does not trigger for a particular PR (for example, the paths it watches were not touched), the PR can get stuck waiting forever. Be careful pairing required checks with path filters, and consider a small always-passing job so the required check is always reported.

Key takeaways

• Required status checks make CI a hard gate, not a suggestion.
• Checks are matched by job name in your workflow file.
• Watch for path filters that can leave a required check perpetually pending.

Related guides