GitHub Merge Queue merge_group Trigger: Fix Checks That Never Start (2026 Guide)
Your rollback PR is approved, but merge queue checks never move beyond Pending. No failures, no logs, no progress. This pattern is usually not a flaky runner problem. It is often a workflow trigger mismatch.
This guide is a practical runbook for fixing merge_group trigger gaps in GitHub Actions so required checks actually start in merge queue context.
Table of contents
1. Quick diagnosis table
| Symptom | Do this first | Why it works |
|---|---|---|
| Required check is pending forever with no run logs | Add merge_group to workflow on: triggers |
Merge queue runs checks in merge-group context, not plain PR context. |
| PR checks are green but queue checks never start | Audit job-level if: conditions for event-name filters |
Hard-coded pull_request guards silently skip merge-group runs. |
| Queue entry restarts and pending repeats | Rebase rollback branch to latest protected tip, then requeue | Fresh snapshots reduce invalidated queue runs. |
| Checks run but branch protection still shows pending | Verify required-check names match actual workflow job names | Name mismatch can leave policy checks unresolved. |
| Incident pressure escalating | Apply minimal trigger fix, keep protections on | Fastest safe path without creating a second incident. |
2. Why merge_group triggers are required
GitHub merge queue validates a queue-generated merge candidate. That candidate emits a merge_group event. If required workflows only subscribe to pull_request, branch protection sees required checks but no corresponding runs in queue context.
Result: rollback PR is approved, but merge queue remains blocked with pending checks forever.
- PR checks: validate branch diff before queue.
- Merge-group checks: validate queue-generated integration snapshot.
- Required checks: must resolve in the same context expected by branch protection.
merge_group trigger is the correct low-risk fix.
3. Workflow patterns that break queue checks
Pattern A: Trigger listens only to pull_request
on:
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm testWorks for PR pages, but queue-required checks never start.
Pattern B: Correct trigger, wrong job guard
on:
pull_request:
merge_group:
jobs:
test:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- run: npm testWorkflow starts, but the required job is skipped in merge-group runs.
Pattern C: Safe baseline for queue-compatible checks
on:
pull_request:
branches: [main]
merge_group:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm test4. 5-minute triage checklist
- Open branch protection and copy exact required-check names.
- Confirm those checks map to active workflow jobs.
- Verify each required workflow includes
merge_grouptrigger. - Audit job-level
if:guards for event filters that skip merge-group context. - Rebase rollback PR branch to latest protected tip and requeue.
- Watch for new run creation in Actions; no run means trigger/guard issue still exists.
5. Queue-safe remediation workflow
- Create a small infrastructure PR that only fixes workflow triggers/guards.
- Merge that fix through normal policy path.
- Requeue the rollback PR without adding unrelated changes.
- Confirm required checks start in merge-group context.
- Complete rollback merge and run production validation checklist.
6. YAML and CLI recipes
Create a minimal trigger-fix branch
git fetch origin
git switch -c fix/merge-group-trigger origin/main
# Edit workflow files under .github/workflows/
git add .github/workflows
git commit -m "Fix merge_group triggers for required checks"
git push -u origin fix/merge-group-triggerQueue-safe rollback branch refresh
git fetch origin
git switch rollback/incident-main
git rebase origin/main
git push --force-with-lease
# Requeue the PR after updated checks are visibleQuick verification via GitHub CLI
# Inspect check rollout for a PR
PR=123
gh pr view "$PR" --json statusCheckRollup,headRefName
# Optional: inspect workflow runs for the branch
gh run list --limit 20 --json databaseId,event,status,conclusion,workflowName,headBranch7. Incident rollout checklist
- Assign incident owner and CI workflow owner.
- Document required checks currently pending and expected workflow files.
- Patch triggers and guards with smallest possible diff.
- Post progress updates in incident channel every queue state change.
- After rollback merge, record fixed workflow commit hash in postmortem draft.
Once stable, review all required workflows for consistent trigger coverage so the same failure mode does not recur in the next rollback window.
8. FAQ
Do all workflows need merge_group triggers?
No. Only workflows that map to required checks for protected branches need merge-group compatibility.
Can skipped jobs still satisfy required checks?
Usually no for strict required checks. A skipped required job often keeps queue readiness unresolved.
Is merge_group needed if we do not use merge queue?
No. It becomes relevant when branch policies depend on merge queue validation.
What if queue checks start but are very slow?
Then investigate runner capacity and queue starvation using the Merge Queue Rollback Stuck Guide.
Where should I go after trigger fixes are done?
Use the Required Checks Guide for direct test/lint failure remediation and the Pending Checks Guide for broader non-start triage.