Merge Queue
Test every pull request against the latest main before it merges, and keep the queue moving with parallel checks and batches.
A pull request can pass CI on its own and still break main, because the pull requests merged ahead of it changed the code it was tested against.
Which problem are you solving?
Section titled Which problem are you solving?| Symptom | What to use | Cause |
|---|---|---|
| PRs pass CI but break main | Lifecycle | CI ran against an outdated main |
| PRs wait hours to merge | Parallel checks | PRs are tested one at a time |
| CI costs keep climbing | Batches | Every queued PR gets its own CI run |
| Every push waits on slow tests | Two-step CI | Fast and slow tests run in one pipeline |
| The queue reruns passing CI | Direct Merge | The queue retests even an up-to-date PR |
| Monorepo PRs block each other | Scopes | Unrelated changes share one queue |
| Hotfixes wait behind feature work | Priority rules | The queue merges in arrival order |
| A CI outage fails every queued PR | Pause | The queue keeps testing while CI is down |
| Approved PRs wait to be queued | Auto-Merge | Nothing queues a PR on approval |
| Stacks get merged by hand | Stacked PRs | Each PR waits for the one below it |
Glossary
Section titled Glossary| Term | Meaning |
|---|---|
| Scope | The part of the codebase a PR touches, used to batch monorepo PRs or test them in parallel. |
| Batch | A group of queued PRs tested together in one CI run. |
| Parallel checks | Speculative CI runs on several queued PRs at once, each on top of the ones ahead of it. |
| Two-step CI | A split where fast tests run on every push and the expensive ones only in the queue. |
| Freeze | A hold that blocks merging for a set window, such as a release. |
Where to go next
Section titled Where to go nextWrite queue rules
Decide which pull requests a queue accepts and the checks they must pass to merge.
Choose a queue mode
Decide whether queued pull requests are tested on top of each other or side by side.
Monitor the queue
Read throughput and wait times on the statistics page or from the CLI.
Was this page helpful?
Thanks for your feedback!