How to Require Passing Checks on Protected Branches

Required checks name the exact CI jobs that must succeed before a PR can merge into a protected branch.

Branch protection can require named status checks. The names must match the job (or check-run) names your workflow reports. Turning on strict mode also forces the branch to be up to date with the base before merge, so checks run against the merged state.

Steps

• Note the exact job names your workflow reports as checks.
• Add those names as required status checks on the protected branch.
• Enable strict mode to require the branch be current with base.
• Add a summary gate job when path filters may skip individual checks.

A gate job for path-filtered checks

jobs:
  test:
    if: needs.changes.outputs.code == 'true'
    runs-on: ubuntu-latest
    steps:
      - run: npm test
  ci-gate:
    needs: [test]
    if: always()
    runs-on: ubuntu-latest
    steps:
      - name: Require test to pass or be skipped
        run: |
          [ "${{ needs.test.result }}" = "failure" ] && exit 1
          echo "gate ok"

Gotchas

• If a required check is skipped and not reported, the PR waits forever; use a gate job.
• Renaming a job breaks the required-check name; update branch protection too.

Related guides