GitHub Pull Request Merge Queue FAQ

In February 2023, GitHub released its pull request merge queue feature in public beta.

If you have no clue what a merge queue is, you can read about it here or watch our video below.

After the announcement, many questions popped up on social media. We built a list of a few questions and answered them below. When possible, we tried to provide alternative solutions to the problem listed in the question.

➡️ Who has access to GitHub Merge queue?

The feature is only available to open-source organizations and GitHub Enterprise Cloud customers. GitHub announced on Twitter they were not thinking about opening up for non-enterprise users (e.g., Team plan customers or personal GitHub accounts).

If you want to use a merge queue and are a private user, you can leverage Mergify instead.

➡️ What kind of rules can I set up for merging pull requests?

The GitHub Merge Queue works on top of branch protections. You will have to enable branch protections to leverage the merge queue.

If you cannot express your merge criteria using GitHub branch protections, you can leverage Mergify, which allows great flexibility in defining those merge criteria.

➡️ Are multiple queues possible to set up?

Using multiple queues is useful to parametrize your queue with different settings regarding merging conditions, CI, etc. Unfortunately, using multiple queues with the GitHub Merge Queue is impossible.

If you're looking for a merge queue with multiple queues support, Mergify allows you to define as many queues as you want and handle queue priorities.

➡️ Can I prioritize pull requests in the Merge Queue based on their importance or urgency?

Currently, GitHub Merge Queue does not allow you to order the pull request in the queue and only supports first in, first out mode (FIFO).

Suppose you're looking into priority support for your queue. In that case, Mergify is an excellent alternative as it allows you to prioritize pull requests in the merge queue based on many factors: the size, complexity, or impact of the changes, the importance or urgency of the feature or bug fix, or the author or reviewer of the pull request, etc.

➡️ How do you unblock the queue?

There are multiple reasons why the queue might be blocked. The CI might not have started or finished yet or crashed. Some users also reported that everything was fine, but GitHub did not seem to merge the PR anyway. Well, remember, this is all in beta.

If your CI has failed to start or finish running its job, ensure you configure your CI timeout correctly in the branch protection settings.

If your queue seems blocked anyhow, the next best thing is to remove the pull request blocking the queue using GitHub UI.

➡️ How do you remove a PR from the queue?

You can remove a pull request from the queue using the "remove pull request from the queue" button.

➡️ How does the Merge Queue handle conflicts and failed builds, and what can I do to resolve them?

If a conflict or CI failure occurs, the merge queue will remove the pull request from the queue. You can then resolve the conflict, fix the failed build, and resubmit the pull request for merging.

➡️ Is the GitHub Merge Queue allowing you to change the commit message when using squash and merge?

The GitHub Merge Queue only allows you to configure the merge method, but the default merge message will be used.

On the other hand, Mergify's merge queue allows you to use a commit message template to help with that.

➡️ Can I use the merge queue with third-party integrations and tools like CI/CD pipelines or code review platforms?

You can set up third-party integrations and tools like CI/CD pipelines or code review platforms.

➡️ How can I control the merge method of my queue?

The GitHub Merge Queue does not allow fine-grained control of the merge method used to build the queue. You will have to use the default merge method, and you won't have complete control over the git tree built by GitHub.

Some other merge queue implementation, such as Mergify, allows for finer-grained control over the method used to build the final git tree, allowing for mixing rebase, squash, and merge all along or even doing fast-forward in some instances.

➡️ Are there any limitations or restrictions on using the Merge Queue, such as the number of pull requests or the repository size?

Yes, you can build up to 100 pull requests maximum, and there is a merge limit of 100 pull requests to merge in a single group. Also, if you merge only non-failing PRs, only pull requests passing their required CI checks can be added to a group.

➡️ How do I monitor and track the progress of pull requests in the Merge Queue?

You can do it through the GitHub interface or by integrating with third-party tools that provide more advanced tracking and reporting capabilities. You can also set up notifications or alerts that notify you or specific team members when pull requests are merged or encounter issues.

The merge queue UI is available by clicking the "merge queue" words in a queued PR. You can also access it via the URL https://github.com/<org>/<repo>/queue/<branch name>.

➡️ My merge queue is slow. Can I make the merge queue go faster?

The merge time in a merge queue highly depends on the CI run time. GitHub Merge Queue does not provide any optimization mode, such as batching, for this. Your only option to make the queue faster is to ensure your CI runs as quickly as possible.

If that's not something you can optimize further, you could use another merge queue. For example, Mergify's Merge Queue supports batching pull requests together, which can multiply your throughput by a 10× magnitude.

➡️ Is there support for using the GitHub Merge Queue effectively and optimizing my pull request workflow?

As the GitHub merge queue is currently in beta, its support is limited and cannot be relied upon yet.

If you are looking for a commercially supported merge queue, Mergify might be your best bet.

✅ Conclusion

This article answers some of the most common questions about the pull request merge queue feature.

No matter what, a merge queue feature is an essential solution that can help you streamline your workflow and collaborate more effectively with your team. By leveraging the power of automation and intelligent merging, you can focus on what matters: building great software that meets the needs of your users and stakeholders.