Required GitHub check stuck on “Waiting for status to be reported”: a safe triage playbook

[canilbey]

A pull request that says “Expected — Waiting for status to be reported” often has no failing job to inspect: branch protection is waiting for a check name that the workflow did not emit for that commit.

I maintain checkgate, a read-only offline CLI for auditing that small contract. This note is a practical triage path you can use with or without the tool.

1. Identify which kind of failure you have

Start with the latest PR commit, not an earlier green commit.

• A workflow run exists and failed: debug that run; this is not a missing-check problem.
• No run exists for the required name: compare the ruleset/branch-protection name with the workflow's emitted job name and inspect workflow-level filters.
• A merge queue stalls only after enqueueing: inspect merge_group support separately from ordinary pull_request support.
• The check name is matrix- or expression-generated: do not assume one static name; inspect the actual check runs GitHub emits.

GitHub's official troubleshooting guide confirms that a workflow skipped by path/branch filtering or a commit message leaves associated required checks pending. It also requires the separate merge_group event for required GitHub Actions checks used by merge queues:

https://docs.github.com/en/pull-requests/how-tos/merge-and-close-pull-requests/troubleshooting-required-status-checks

2. Audit the local contract offline

Copy the exact required check names from the target branch's ruleset or branch protection into a newline-delimited file:

unit-tests
lint
security-scan

Then run:

checkgate audit \
  --workflows .github/workflows \
  --required-file required-checks.txt

For a repository that actually uses merge queues:

checkgate audit \
  --workflows .github/workflows \
  --required-file required-checks.txt \
  --require-merge-group

Interpret the result as a contract audit, not as proof of live branch settings:

• REQUIRED_CHECK_NEVER_EMITTED: no statically resolvable job emits that required name.
• REQUIRED_CONTEXT_RENAMED: a similar current job name suggests stale protection configuration.
• REQUIRED_CHECK_NOT_ON_PULL_REQUEST: the matching job cannot run for PRs.
• WORKFLOW_PATH_FILTER_CAN_SKIP_REQUIRED: workflow-level paths/paths-ignore can suppress the entire required workflow.
• MERGE_GROUP_TRIGGER_MISSING: merge-queue validation was requested, but the workflow lacks merge_group.
• REQUIRED_CONTEXT_UNVERIFIABLE: expressions or matrices prevent a safe static conclusion; review manually rather than treating this warning as a failure.

Text, JSON, and SARIF output are available. Exit codes are 0 for no contract errors, 1 for findings, and 2 for invalid input/YAML.

3. Verify before changing protection

Before removing or renaming a required check, confirm all three sides:

1. the exact required name in the target branch's active ruleset/protection;
2. the job/check name emitted for the latest PR SHA;
3. whether every PR that must merge can trigger that workflow.

For merge queues, repeat the check against the merge-group event path. A workflow can be correct for pull_request and still fail to report on a queued merge group.

Do not “fix” this by blindly setting a success status or weakening protection. Prefer making the intended required check report consistently, or deliberately changing the required contract with repository-owner review.

Reproducible trial and evidence

The repository includes a 60-second isolated trial with one safe fixture and one intentionally broken fixture:

https://github.com/canilbey/checkgate#try-it-in-60-seconds

Public-workflow dry runs and the limits of those claims are recorded here:

https://github.com/canilbey/checkgate/blob/main/VALIDATION.md

Version 0.1 intentionally does not query live rulesets, resolve reusable workflows, or expand dynamic matrix/expression names. If you try it, use the structured feedback form for a minimal public example—never paste private workflows, secrets, proprietary logs, or personal data:

https://github.com/canilbey/checkgate/issues/new?template=feedback.yml