Ever feel like you're constantly in a race to merge your pull request (PR) before someone else jumps in and creates a conflict? Many engineers developing against the same trunk branch can lead to merge mayhem.
Enter the GitHub merge queue. This new feature automates merging PRs into the trunk branch, keeping your code stable and your team productive. This guide covers what a merge queue is, how to set one up in GitHub, and what best practices you should follow to unlock its full potential.
The GitHub merge queue ensures that PRs are merged in an orderly and controlled manner, minimizing the risk of conflicts and regressions due to concurrent merges. Using the GitHub merge queue offers several key benefits over manual merges:
- The trunk branch is always green, keeping development unblocked.
- The queue proactively identifies and prevents conflicts before merging, meaning less time spent troubleshooting broken builds.
- Automated merging reduces developer overhead.
How to use the GitHub merge queue
GitHub currently offers merge queues for organization accounts. You can use GitHub merge queues in public repositories owned by any organization or in private repositories owned by organizations using GitHub Enterprise Cloud.
To enable merge queues for an eligible repository, you need to access its branch protection settings. You can do that only if you have administrator access to the repository.
Navigate to the Settings tab of the repository and click on the Branches option from the left navigation pane:
Next, add a branch protection rule to the repo by clicking the Add branch protection rule button. You will see a form asking for a branch name pattern on which the rule will be applied and allowing you to set up a few options. If you scroll down, you will find the Require merge queue option:
Check the box next to it to enable it. Once enabled, you can configure additional options such as merge method, build concurrency (how many queued PRs are to be built simultaneously), and merge limits (how many PRs to merge simultaneously and in a given time frame). Configure these options and click on the Create button at the bottom:
You can now try creating a PR to your main branch from another branch. You'll notice that the merge button at the bottom of the PR says Merge when ready, which means that once you mark this PR as ready to be merged, it will be added to the merge queue and merged in a group to the main branch:
This means that the merge queue has been set up correctly!
You can now add continuous integration (CI) checks and review requirements to the branch to better moderate the PRs that get merged into it. You can also configure CI checks to be run when a PR gets added to the merge queue. You can do this by using the merge_group event if you're using GitHub Actions or by configuring your external CI runner to listen for pushes to branches with the special prefix gh-readonly-queue/{base_branch}.
Downsides of GitHub's merge queue
Now that you understand how GitHub's merge queue works, here are a few potential downsides that you should be aware of before using them.
First, not all teams will benefit equally from merge queues. If your repos handle only a handful of PRs every week, using the GitHub merge queue might not provide you with any particular velocity or collaboration benefits.
Additionally, users report that the GitHub merge queue runs CI checks for a second (redundant) time in quite a few scenarios, which results in wasted CI resources.
Finally, users report difficulties with state clarity. It can be tricky to quickly tell why a build failed just by looking at the PR after the failure. Also, it is difficult to access the build currently running in a queue from the corresponding PR(s), requiring several additional clicks to get the information you need.
All this means that while GitHub's merge queue may help your team work more efficiently, it can also introduce new developer overhead and CI costs. Make sure you evaluate your requirements and explore options like Graphite to find the best merge queue for your team.
