GitHub’s merge queue lines up approved pull requests, tests each one together with the changes ahead of it, and merges it when the required checks pass. If a queued pull request conflicts with the base branch or fails a required check, GitHub removes it from the queue, and the author fixes it and queues again.
What a merge queue is for
On a busy branch, a pull request can pass its checks and still break main, because it was tested against an older main. A merge queue closes that gap. It builds a temporary branch containing the target branch, the pull requests ahead in the queue and yours, runs your required checks on that combination, and merges only if they pass.
How to enable merge queue on GitHub
- In the repository settings, edit the branch protection rule or ruleset for the target branch.
- Turn on Require merge queue, then choose the merge method and group settings.
- Update CI to run on the
merge_groupevent, so required checks report on the queue’s temporary branches. - On an approved pull request, select Merge when ready to add it to the queue.
on:
pull_request:
merge_group:GitHub documents which plans and repository types include merge queue, so check that before you plan around it. See managing a merge queue.
How the queue groups and tests pull requests
The queue works in merge groups. Each group is a temporary branch, named with the gh-readonly-queue/ prefix, that holds the target branch plus one or more queued pull requests in order. Your required checks run against that branch through the merge_group event. Settings on the rule control how many pull requests go into a group, how many groups build at once and how long the queue waits for checks.
If a group passes, its pull requests merge. If it fails, GitHub removes the failing pull request and rebuilds the groups behind it.
What happens when a queued pull request conflicts
GitHub’s documentation is specific: if there are failed required status checks or conflicts with the base branch, the pull request is removed from the queue, and the pull request timeline shows why. The author merges or rebases onto the base branch, resolves the conflict, waits for checks and queues again.
That works when conflicts are rare. With many pull requests in flight, each removal costs a rebase, a CI run and a wait, and the pull requests behind it are tested again.
What merge queue does not do
- It does not resolve merge conflicts. It detects them and removes the pull request.
- It does not look at code relationships. A renamed function and a new call to its old name are caught only if your checks fail on the combination.
- It does not write the fix. The author, or their coding agent, does.
Merge queues and coding agents
Coding agents multiply the pull requests open against a repository. A merge queue keeps main green at that volume, but each removal still sends work back: an agent session to rebase and resolve, a CI run to check it, and a developer to restart both. The more pull requests are in flight, the more of them conflict. See what merge conflicts cost.
When GitHub’s merge queue is enough
If your pull requests rarely conflict and your checks catch what matters, the native queue may be all you need. Look at an alternative when pull requests are removed from the queue often, when the same branches are rebased again and again, or when main breaks from changes that merged cleanly.
Alternatives to GitHub merge queue
| Feature | Merget | GitHub merge queue | Mergify | Graphite | Aviator |
|---|---|---|---|---|---|
| Resolves merge conflicts | Yes | No | Mechanical conflicts only, in Preview | No | No |
| Finds conflicts Git merges cleanly | Yes | No | No | No | No |
| Who fixes a conflict | The queue | The author | The author, unless it is mechanical | The author | The author |
Compare the alternatives in detail, with links to each vendor’s documentation.
Merget: a merge queue that resolves the conflict
Merget runs its own queue on GitHub. It works with public and private repositories, for organizations and personal accounts, and needs no label, comment or enqueue command. It finds conflicts between open pull requests, including the ones Git merges cleanly, resolves them in queue order, and lands the result through your required checks and reviews. It starts in Advisory mode, which changes no source code.
On a branch that also uses GitHub’s native merge queue, Merget still prepares pull requests and you merge through GitHub’s queue. To let Merget land work itself, remove GitHub’s merge queue rule from that branch. Read the setup guide.
Questions
What is a merge queue in GitHub?
A merge queue is a GitHub feature that lines up pull requests, tests each one with the changes ahead of it, and merges it when required checks pass, so main stays green on a busy branch.
How do I enable merge queue on GitHub?
Turn on Require merge queue in the branch protection rule or ruleset for the branch, and make sure CI runs on the merge_group event.
Does GitHub merge queue resolve merge conflicts?
No. A pull request that conflicts with the base branch is removed from the queue, and its author resolves the conflict and queues again.
Why was my pull request removed from the merge queue?
Usually because a required check failed on the queued combination or the pull request conflicts with the base branch. The pull request timeline shows the reason.
What are some alternatives to GitHub’s merge queue?
Merget, Mergify, Graphite, Trunk and Aviator. Merget is built to resolve conflicts between parallel pull requests instead of removing them.
See how Merget resolves conflicts in queue order, or sign up free and connect one repository.