Identify which revision failed
An engineering lead introduces a merge queue and sees pull requests removed despite green PR checks. Record the merge-group run and its temporary revision. The queue tests the proposed change together with the latest target branch and changes ahead of it. A passing PR build is useful, but it did not necessarily test that combination.
- Separate no check reported, an actual test failure, a conflict and a queue timeout.
- Retain the group revision and the first failing step, not only the PR number.
Make CI listen to the queue
For GitHub Actions, inspect whether each required-check workflow includes merge_group as well as its ordinary PR event. A workflow configured only for pull_request or push does not automatically handle merge_group. For an external CI provider, inspect support for temporary branches beginning gh-readonly-queue/{base_branch}; do not copy an Actions-only fix into another provider.
- Check filters and expressions for assumptions that every run has pull-request fields.
- Keep required check names consistent with the target branch's rules.
Do not chase a stale group
The queue can recreate downstream temporary branches when an earlier PR fails or is removed. Confirm that the result being inspected belongs to the current group, not a superseded one. If an actual test fails only in the combined state, reproduce that state on a safe branch and investigate the interaction; enabling another trigger alone will not repair it.
- Avoid repeatedly moving PRs to the front as a substitute for finding the fault.
- Do not disable a check simply because the queue is slower than a PR run.
Evidence for acceptance
On an authorised test route, show that a queued change receives the named required results on its merge-group revision. Also show a deliberate failing check prevents the agreed queue merge. Record trigger and SHA in the handover. This verifies the queue path, not production deployment or all future combinations. Send redacted queue symptoms initially; any repository settings change remains an account-holder decision.
Sources and limits
- GitHub: managing a merge queue Checked 2026-10-10.
- Required GitHub Actions workflows need the merge_group event for merge queues.
- Queue checks evaluate changes combined with the latest target branch and preceding queued changes, on a different SHA from the pull request.
- External CI must handle the documented gh-readonly-queue branch prefix.