Lesson 10 of 30

Branch Protection and Required Checks

Q: You've set up a CI pipeline and it reports pass/fail correctly. How do you actually make it so a PR can't merge unless that pipeline is green — and what could break that setup silently?

A strong answer covers: Names the actual mechanism: branch protection's required status checks, matched by the reported check run's exact name; States that GitHub enforces it at the merge-button level, independent of reviewer approval; Identifies at least one way this silently breaks: a renamed job, a matrix job's per-leg naming, or a conditional job that never runs on this PR's trigger; Mentions the 'up to date' / strict requirement, or merge queue, as the piece that governs staleness.

A green pipeline means nothing until you tell GitHub to treat it as a merge gate. Required status checks are how CI stops being advisory and starts being enforced.

14 min read

Check your understanding

Every option explains itself — why the right one is right, and why each wrong one is wrong. Miss one and it comes back later on a spaced-repetition schedule.

No quiz for this one — it's a practical topic

This topic is about judgment and practical tradeoffs more than a single right answer — a mock interview is the better way to test yourself on it.

Be interviewed on this →

Stuck? Ask the AI tutor

Hints without spoilers, and a plain explanation of why a wrong answer was wrong — answered only from this lesson. Free account, no card.

Interview questions on Branch Protection and Required Checks

What interviewers actually ask about this, and what a strong answer has to cover.

You've set up a CI pipeline and it reports pass/fail correctly. How do you actually make it so a PR can't merge unless that pipeline is green — and what could break that setup silently?

A strong answer covers

Names the actual mechanism: branch protection's required status checks, matched by the reported check run's exact name
States that GitHub enforces it at the merge-button level, independent of reviewer approval
Identifies at least one way this silently breaks: a renamed job, a matrix job's per-leg naming, or a conditional job that never runs on this PR's trigger
Mentions the 'up to date' / strict requirement, or merge queue, as the piece that governs staleness

Likely follow-ups

If that job is inside a matrix build, what exactly do you need to type into the required-checks list?
Suppose the job is wrapped in an `if:` condition and, on this particular PR, that condition evaluates to false. What happens to the merge button?
What's the difference between 'require branches to be up to date' and a merge queue re-checking against the hypothetical merged state?

Practice these with the AI interviewer →

The plain-language idea

By default, a CI pipeline is just informational. It runs, it reports pass or fail, and a reviewer can merge the PR anyway — green checkmark, red X, doesn't matter, the merge button works either way. Required status checks change that: you tell the repo "this named check must pass before the merge button unlocks," and GitHub enforces it mechanically. No amount of reviewer approval overrides a required check that's still red or still pending.

The mechanism underneath is simpler than it sounds: every job in a workflow reports its result back to GitHub as a check run, identified by the job's name. Branch protection doesn't know anything about YAML, triggers, or steps — it just watches for a check run with a specific name to report success on the commit a PR is trying to merge. If that name never appears at all, the rule treats it as permanently unsatisfied, not as "not applicable."

See it in a real thing: making a matrix job requirable

Say this repo's verify job (from the pipeline-anatomy lesson) starts testing against two Node versions instead of one:

jobs:
  verify:
    name: Type-check, lint, test, validate content, build
    strategy:
      matrix:
        node-version: [20, 24]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: pnpm
      # ...same steps as before

A matrix job doesn't report one check run — it reports one per matrix leg, named by combining the job's name with the matrix value: Type-check, lint, test, validate content, build (20) and Type-check, lint, test, validate content, build (24), as two independent entries. If you go into branch protection and require only the un-suffixed name, it will never match either leg — the rule stays permanently unsatisfied and blocks every merge. You have to require the exact suffixed names, both of them, individually.

Setting that up via the GitHub CLI instead of clicking through Settings — useful because it's scriptable and reviewable as a diff, unlike a UI change:

gh api repos/adeshukla/praxis/branches/main/protection \
  --method PUT \
  --field required_status_checks='{"strict":true,"contexts":["Type-check, lint, test, validate content, build (20)","Type-check, lint, test, validate content, build (24)"]}' \
  --field enforce_admins=true \
  --field required_pull_request_reviews='{"required_approving_review_count":1}' \
  --field restrictions=null

strict: true is "require branches to be up to date before merging" — a passing check only counts if it ran against a commit that already includes the latest main, not a stale branch point.

What people usually miss

Watch out

"Required" and "ran" are not the same thing. A required check that never triggers — because its workflow's trigger doesn't fire on this PR, or an if: skipped the job — reads to branch protection as "still waiting," not "not applicable." The merge stays blocked with no obviously wrong signal to debug.
A matrix job's checks are named per leg, not once. Requiring the base job name when the job is a matrix silently requires nothing, because that exact name never appears as a check run.
Merge queue re-checks the hypothetical merged state, not just your branch. If this repo turns on merge queue instead of plain "require up to date," a PR's checks get re-run against what main would look like after merging — catching a break that only shows up when your change combines with something someone else merged five minutes ago, which a same-PR-only rerun can't catch.

The genealogy: the CI-facing half of a merge gate

How GitHub turns "an approving review" and "a passing check" into a locked merge button — the review-side mechanics, the admin-bypass gotcha, the fact that none of this lives in git history at all — belongs to GitHub's own hosting policy layer, covered elsewhere. This lesson is the other half: shaping the pipeline itself so that it produces a check run worth requiring in the first place, and getting that check run's exact name right in the rule that references it.