Introduction

Pull requests often get blocked not because the deployment failed, but because GitHub never received the exact status check it expected. The deployment may have succeeded in logs while the pull request still shows Expected — Waiting for status to be reported or a permanently pending check. In most cases, the mismatch is between branch protection requirements and the actual job or workflow that reports status.

Symptoms

  • A pull request stays blocked on a pending required check
  • The related workflow completed, but the check on the PR did not resolve
  • Branch protection lists a check name that no longer exists after workflow refactoring
  • A deployment job runs on push, but the pull request never receives its corresponding status

Common Causes

  • Branch protection requires the wrong check name
  • The workflow trigger does not run in the pull request context that reports status back to the PR
  • The job or workflow name changed, but branch protection was not updated
  • The expected deployment gate runs in a different event or branch than the PR validation path

Step-by-Step Fix

  1. 1.Check which exact status names branch protection requires
  2. 2.GitHub matches required checks by name, not by what humans think the workflow represents.
  3. 3.Compare required check names with actual job names
  4. 4.A renamed job can leave branch protection expecting a check that will never appear again.
bash
gh api repos/{owner}/{repo}/commits/{sha}/check-runs
  1. 1.Make sure pull request workflows actually report into the PR
  2. 2.If the validating workflow only runs on push, the deployment may succeed on the branch but never satisfy the required pull request check.
yaml
on:
  pull_request:
  push:
  1. 1.Update branch protection when job structure changes
  2. 2.After renaming or splitting jobs, remove obsolete required checks and add the current ones.

Prevention

  • Keep branch protection rules synchronized with workflow job names
  • Avoid unnecessary job renames on critical required checks
  • Ensure required validation paths run in the pull request context
  • Review check-run names after workflow refactors, not only after merge failures