What is a merge queue?

Greg Foster
Greg Foster
Graphite software engineer

When building software with a large team of contributors, collaboration is a key factor in determining overall productivity (or a team's velocity). In most cases, developers work together on code changes and propose modifications through pull requests (PRs). These PRs undergo a review process, and once approved, the changes need to be integrated through a process known as merging.

However, managing merges, especially in projects with high PR activity, can become a challenge. Multiple PRs might include changes to the same code sections, leading to conflicts that require manual intervention. Additionally, pre-merge checks (such as builds and tests) can often take as long as ten minutes per run, adding to the time spent rebasing and merging PRs.

Here's where merge queues come in. A merge queue acts as a holding area for approved PRs, streamlining and automating the merging process. You can imagine it as a virtual line where PRs wait their turn for integration.

Merge queues offer increased development velocity, reduced risk of CI failures, and improved code quality. However, not every team needs merge queues. If used incorrectly, merge queues might even end up slowing you down. So it's important to check whether your workflows could really benefit from a merge queue. Some key indicators that you need a merge queue are as follows:

  • Your developers spend a lot of time rebasing their PRs to prepare them for merging.
  • Your CI systems have long-running checks, and your teams submit a high number of PRs every day.
  • Your codebase often regresses (unexpected bugs are introduced by new code) after merging a lot of PRs.

Here's a quick overview of how merge queues work:

  1. PR submission and approval: Developers submit PRs containing their code changes. These requests undergo a manual code review process, during which other developers assess the code's quality and alignment with project requirements. Once approved, the PR is considered ready for merging.
  2. Addition to the queue: The PR is then added to the merge queue. There are various ways to do so. In some systems, a specific label (eg merge-ready) might be applied to the PR, signaling its readiness. Alternatively, a dedicated user with merge privileges might manually add it.
  3. Automatic checks: Once in the queue, the merge queue system typically triggers automatic checks on each PR. To do this, the merge queue creates temporary branches for every PR with the code from the base branch, the code changes in the PRs ahead of it (if there are any), and the code changes it carries. These checks might involve building the code with the proposed changes, running unit tests, and performing other quality assurance measures.
  4. Merging based on queue order and checks: If all checks pass for a particular PR's temporary branch, the queue system automatically merges its changes into the target branch.
  5. Handling of conflicts and reruns: If a merge conflict arises or a check fails for any PR, the merge queue automatically removes the PR from the queue, notifies the developers of the failure, and continues with the remaining PRs in the queue. Once the error is resolved, the PR can be re-queued for another merge attempt.

While this is how a typical merge queue functions, some implementations offer additional features, such as batch merging, which allows you to combine two or more PRs together to reduce your CI usage and merge efficiently. Such features help you implement custom DevOps workflows in your systems.

Merge queues are becoming increasingly popular in version control systems. Launched in July 2023, the popular version control platform GitHub offers a native merge queue feature. This allows repository administrators to enable queueing for specific branches, ensuring a smooth and automated merging process.

Additionally, several third-party tools integrate with popular version control systems like GitHub to provide advanced merge queue functionalities. A popular example is the Graphite merge queue, which offers stack-aware merges and supports features such as priority management, fast-forward merges, and queue pauses.

Stay unblocked. Ship faster.
Experience the new developer workflow - create, review, and merge code continuously. Get started with one command.
Get started

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2