GitHub Merge Queue Required Check Name Mismatch: Fix Waiting for Status During Rollback (2026)
Your rollback PR is approved, workflows appear green, but merge queue still shows Waiting for status to be reported. This usually means GitHub is waiting for an exact required-check context that no longer matches what your workflows emit.
This guide is a practical incident runbook for required check name mismatch failures in merge queue: detect drift fast, align policy with stable check names, and land rollback safely without force-push or blind bypass.
Table of contents
1. How to confirm name mismatch quickly
| Observed signal | Likely meaning | Immediate action |
|---|---|---|
| PR shows "Expected" or "Waiting for status to be reported" for one check | Required context name is not emitted by current workflow/job names | Compare branch-protection required names against recent check-run names. |
| pull_request checks pass, merge queue stays pending | merge_group path emits different check names or no run at all | Verify same required gate names appear in both events. |
| Renamed job/workflow this week, pending started after | Policy drift after rename | Update required-check list or restore previous stable gate name. |
| Only matrix job names appear (for example test (py3.12)) | Dynamic names do not match static required policy | Add one stable gate job and require that job only. |
| Required checks changed during incident | Mid-incident policy churn | Freeze policy changes, align once, and requeue a single clean attempt. |
2. Common root causes
- Workflow/job rename drift: required check still references old job name.
- Event mismatch: required jobs run on
pull_requestbut not onmerge_group. - Dynamic matrix labels: required list expects static check name, runs emit variable matrix names.
- Conditional skip:
if:guard skips job for queue event, so required context never appears. - Cross-repo reusable workflow rename: gate name changed upstream without policy sync.
- Incident-time policy edits: multiple people update branch protection and lose stable mapping.
3. 7-minute triage workflow
- Capture exact required-check names from branch protection for the target branch.
- Collect last 3 queue runs and list emitted check-run names exactly as shown.
- Mark each required name as
foundormissing. - Confirm workflows for missing names subscribe to both
pull_requestandmerge_group. - Inspect job-level
if:guards that may skip queue runs. - If matrix names are required, replace with one stable gate job name.
- Apply one policy/workflow alignment change, then requeue once.
Keep a compact incident ledger for each rerun: timestamp, expected_name, observed_names, fix_applied, outcome. This prevents repeated blind retries.
4. Safe fix patterns
A) Stabilize required names
- Define one queue gate job with a stable name (for example
required-ci). - Avoid requiring dynamic matrix child names in branch protection.
- Treat job-name changes as breaking changes requiring policy update PR.
B) Keep event parity
- Ensure required workflows run on both
pull_requestandmerge_group. - Keep queue-compatible guards: no event-specific skip that suppresses required jobs.
- Use the same gate name for both events so policy stays simple.
C) Incident governance
- Freeze required-check edits after first alignment during active incident.
- Record who changed policy, why, and when in incident timeline.
- If temporary profile is used, add explicit expiry and restoration owner.
5. Workflow and policy recipes
Queue-safe required workflow pattern:
name: required-ci
on:
pull_request:
merge_group:
jobs:
required-ci:
name: required-ci
if: ${{ github.event_name == 'pull_request' || github.event_name == 'merge_group' }}
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm test -- --runInBand
Incident name-drift ledger example:
# timestamp, required_name, observed_names, action, result
2026-02-16T20:02:00Z required-ci "test (node20), lint" set stable gate name pending
2026-02-16T20:06:00Z required-ci "required-ci, lint" requeue once pass
Policy review checklist before changing required checks:
- Is the check name stable across pull_request and merge_group?
- Does this name come from a gate job (not matrix variant)?
- Has branch protection list been updated in the same change window?
- Is rollback runbook updated with new expected names?
6. Guardrails to prevent recurrence
| Metric | Healthy target | Alert threshold |
|---|---|---|
| Expected/waiting-required-check incidents | 0 per week | > 1 per week |
| Required-name changes without policy update | 0% | > 0% |
| Queue reruns before first name-audit | <= 1 | > 2 |
| Rollback queue-to-merge latency | < 15 min | > 30 min |
A lightweight prevention control is enough: PR template checkbox for "required check names changed" plus automatic drift check in CI that compares emitted names against branch policy.
7. FAQ
Why does GitHub show waiting for status even though workflows run?
Because branch protection waits for an exact context name. If current workflow/job names differ, GitHub cannot match the required check.
Can merge queue use different names than pull_request runs?
Yes. Event wiring and conditional logic can produce different check names or skip required jobs in merge-group context.
What is the safest incident fix?
Align required checks to one stable gate name that is emitted in both pull_request and merge_group workflows, then requeue once.
Should we rename required checks during active rollback?
Only once with explicit owner and audit note. Repeated renames during incident generally increase delay and confusion.
How do we avoid recurrence?
Use stable gate-job names, review required-check drift in workflow PRs, and test merge-group parity before rollout.