Table of contents
- What is a merge queue?
- Why merge queues matter
- How merge queues work
- Example scenario
- Real-world benefits
- Comparing merge queue tools: GitHub, Mergify, and Graphite
- When to use merge queues
- Conclusion
What is a merge queue?
A merge queue is an automated system that sequences pull requests (PRs) for merging into a target branch—typically main. It makes sure each PR is up‑to‑date with the latest changes and passes continuous integration (CI) checks right at the moment it merges. Instead of manually merging and risking conflicts or broken builds, developers submit approved PRs into a queue. The merge queue rebases or merges the latest main into each PR, reruns CI, and merges only if all tests pass.
Why merge queues matter
Merge queues help maintain branch stability by preventing "merge wars"—situations where simultaneous merges cause conflicts or failing builds. By automatically rebasing or merging in the latest main changes, the queue ensures that all merged PRs have passed CI tests in the most current context. This reduces the overhead of manual rebasing and waiting for CI tests, allowing developers to stay productive and focused on writing code.
Additionally, merge queues can optimize CI resource usage by intelligently batching PRs together or using speculative checks, running fewer redundant jobs and saving time and computational resources. Teams using merge queues typically see improved collaboration because developers can trust the fairness and orderliness of merges.
How merge queues work
When a PR is approved and ready for merge, it is placed into the merge queue. The queue then merges or rebases the latest main into the queued PRs, creating temporary branches. CI tests run on these temporary branches, ensuring compatibility with the current state of the target branch.
If a PR passes the CI checks, it merges automatically. If the checks fail, the PR is removed from the queue, allowing developers to resolve issues before re-submitting. This ensures the main branch remains stable and continuously deployable.
Example scenario
Imagine one developer submits PR1, which passes initial CI and is added to the merge queue. Another developer submits PR2, which depends on PR1 and enters the queue behind it. The merge queue first rebases PR1, runs CI, and merges it upon success. Next, the queue rebases PR2 on the updated main, runs CI again, and merges if tests pass. If PR2 fails, it's removed from the queue, leaving PR1 safely merged.
This process ensures PR dependencies and integration points are consistently respected, avoiding broken builds and unstable merges.
Real-world benefits
Companies like GitHub and Uber have publicly documented their success with merge queues. GitHub has leveraged merge queues to safely merge tens of thousands of PRs daily, significantly reducing broken builds. Uber implemented merge queues in their monorepo, increasing their mainline reliability from around 50% to over 90%, greatly enhancing developer efficiency.
Comparing merge queue tools: GitHub, Mergify, and Graphite
GitHub merge queue (native)
GitHub's merge queue integrates directly into its repository management, offering features like configurable merge strategies (merge, rebase, squash), concurrency settings, queue jumping, and automatic handling of failing PRs. It requires using GitHub Actions or supported CI platforms to manage the merge queue effectively.
Mergify merge queue
Mergify is a flexible, third-party solution that supports advanced features like speculative checks (testing PRs in advance) and batch processing to speed up merging. Teams appreciate Mergify's support for multiple parallel queues, prioritization rules, and conditional merging.
Graphite Merge Queue
Graphite's merge queue specifically targets teams working with stacked PRs (PRs that depend on other PRs). It automates rebasing, resolving conflicts, and merges entire stacks efficiently using parallel CI runs. Graphite optimizes CI resource usage, providing a robust solution for teams managing complex dependencies and high PR throughput.
When to use merge queues
Merge queues are particularly beneficial for:
- Active repositories with frequent merges.
- Projects with long-running CI pipelines, where re-running tests is expensive.
- Teams using monorepos or stacked PR workflows.
- Distributed teams needing automated and reliable merge processes.
Conclusion
Merge queues play a crucial role in modern software development, automating and optimizing the merging process to keep the main branch stable. Choosing the right merge queue tool depends on your workflow complexity and team needs:
- GitHub's native solution works seamlessly within its ecosystem.
- Mergify excels with flexibility and advanced queue management.
- Graphite provides unmatched efficiency for managing complex, stacked PR workflows.
Adopting a merge queue can significantly enhance your team's productivity, collaboration, and codebase reliability.