Required status checks — what runs and what must pass

There is a large difference between a pipeline that runs on every pull request and a pipeline that must pass before the merge button unlocks. The first is information: a red X that a reviewer may or may not look at. The second is a control: the merge is refused by the server. Teams routinely believe they have the second and have only the first, because nobody checked which contexts are actually in the required list.

Required is a list of names

A status check reports a result against a commit under a name - the context. Branch protection holds a list of context names, and a merge is permitted only when every name in that list has reported success on the head commit.

The consequence is that the coupling between the pipeline and the protection rule is a string. Rename the job that produces terraform-validate to tf-validate, and the old context stops reporting. The rule keeps waiting for a name nothing will ever send.

REPO=example-org/infra-prod
BRANCH=main
gh api "repos/$REPO/branches/$BRANCH/protection/required_status_checks" \
  --jq '{strict: .strict, contexts: .contexts}'

flowchart LR
    A["pull request head commit"] --> B["CI runs jobs"]
    B --> C["contexts reported"]
    C --> D{"every required context green?"}
    D -->|"yes"| E["merge unlocked"]
    D -->|"missing context"| F["merge blocked, waiting forever"]
    D -->|"failure"| G["merge blocked, fixable"]
    H["required list in protection rule"] --> D

The two blocked outcomes feel identical to an engineer and are entirely different in kind. A failure is the control working. A missing context is the control jammed: nothing is red, nothing is running, and the pull request sits pending until someone with admin rights loses patience.

Strict mode: up to date before merging

Strict mode requires the pull request branch to be current with the base branch before merging. Without it, two pull requests can each pass their checks in isolation and produce a broken base branch when both land - the classic semantic conflict, where neither diff is wrong but their combination is.

The cost is throughput: every merge invalidates every other open pull request, which must update and re-run. On a busy repository this becomes a queue that never drains. The resolutions, in order of preference:

• Merge queue. The branch is tested with the pending merges applied, batched, and merged in order. This gives strict-mode safety without the re-run storm.
• Strict mode without a queue. Correct for a repository with low merge volume, which describes most infrastructure repositories.
• Neither. Acceptable only where the code cannot semantically conflict, which for infrastructure is rarely true - two modules can both be valid and jointly break a plan.

What to require on an infrastructure repository

The list should be short, fast, and deterministic:

• Syntax and schema validation for whatever the repo holds - Terraform, Kubernetes manifests, Ansible.
• Policy evaluation for the rules that cannot be left to human review, such as forbidding wildcard IAM statements or privileged containers.
• Secret scanning on the diff.
• A plan or dry-run that renders the change and fails on anything destructive without an explicit acknowledgement.

Everything else can run and report without being required. A required check must be one whose failure genuinely means “this must not merge”; anything flaky in the required list teaches the team to bypass.

Production discipline

1. A check that is not required is not a control. Decide deliberately which are which, and write the decision down.
2. Every required context must always report. Conditional jobs must exit success rather than not run.
3. Bypass is an incident record. If an administrator merges past a required check, that event gets a ticket and a review, not a shrug.

Cross-course references

• Terraform for Production Sysadmins - the plan-as-a- required-check pattern is the core of safe Terraform delivery, and its failure modes are covered there in depth.
• Kubernetes for Production Engineers - admission policies are the cluster-side equivalent of a required check, applied after the merge rather than before.
• Observability for Production Engineers - the parts on pipeline signals cover alerting when a required check has stopped reporting.

Quiz