A merge queue is an automated system that merges pull requests one group at a time, testing each against the latest state of the target branch first, so changes that pass CI in isolation cannot break the branch when combined.
What problem does a merge queue solve?
The stale-CI problem. Your pull request passed its checks, but it passed them against the main branch as it existed when CI last ran. By the time you press merge, five other pull requests have landed. Git may combine everything without a textual conflict and still produce a broken result: your change calls a function someone else just renamed, or relies on behavior another merge removed. Nothing in branch protection catches this, because each change was green on its own. The manual fix is updating your branch and re-running CI before merging, but on a busy repository that becomes a race: by the time your re-run finishes, main has moved again. Teams end up with developers babysitting the merge button, or with a main branch that breaks weekly for reasons no single PR caused.
What is a merge queue doing under the hood?
Instead of merging immediately, an approved and green pull request is added to a queue. From there, per the GitHub merge queue docs, the process looks like this:
- The queue creates a temporary branch containing the speculative merge result: the latest target branch, plus the queued pull request, plus any pull requests ahead of it in line.
- Required CI checks run against that merge group, not against the stale branch.
- Pull requests merge in first-in-first-out order, each only after its group passes.
- If a group fails, the failing pull request is removed from the queue and the speculative merges behind it are rebuilt without it.
Batching is the efficiency trick: by testing several queued pull requests together in one merge group, the queue validates many changes with one CI run and keeps throughput high even when each run takes twenty minutes. Batch size and merge method are configurable per repository, so teams can tune throughput against CI cost.
Who needs a merge queue?
The queue earns its complexity in proportion to merge traffic. Signals that you have crossed the line: developers regularly click update branch two or three times before a merge sticks, main breaks from combinations of individually green changes, or merge order has become something people coordinate in chat. High-traffic monorepos and teams practicing trunk-based development hit this earliest, since everyone is landing small changes into the same branch all day. If that is you, our deep dive on the GitHub merge queue covers setup, CI wiring, and the operational sharp edges.
What does a merge queue not do?
A queue automates the last step, not the judgment before it. It does not review code, and it does not loosen required reviews; a pull request still needs its approvals and passing checks just to enter. It also does not decide that a pull request is ready, which is auto-merge territory; the two compose nicely, with auto-merge queueing the PR the moment review completes. And it cannot save you from flaky tests: a queue amplifies test unreliability, because one flaky failure now ejects a pull request and re-runs everything behind it. Green must mean green for the queue to mean anything.
Frequently asked questions
Does a merge queue replace required reviews or CI?
No. It sits after them. A pull request still needs its approvals and passing checks to enter the queue; the queue then re-runs required checks on the speculative merge result. Think of it as a final gate that validates the combination, not the individual change.
What happens when a pull request fails in the merge queue?
It is removed from the queue rather than merged, and the queue rebuilds the speculative merges for the pull requests behind it without the failing change. The author fixes the problem and re-queues. Everything else keeps flowing, which is the point of the design.
Do small teams need a merge queue?
Usually not. The stale-CI problem grows with merge frequency. A team merging a few pull requests a day can just update branches before merging. Once merges start racing each other daily, or updating branches becomes a full-time chore, a queue starts paying for itself.
