A merge queue prevents semantic merge conflicts by automating the rebase process during merge and ensures that the trunk branch stays “green"—helping development teams move faster with less breakages.
Note
Ready to start using the Graphite Merge Queue? See Set up the Graphite merge queue.
Why Graphite's merge queue?
You would likely benefit from a merge queue if:
Your
trunkbranch is frequently brokenYou're consistently slowed down from rebasing changes
You have the combined issue of long-running checks with a high PR merge rate
Traditional merge queues provide many benefits, but they can also slow teams down by enforcing the ordering of commits and validating those commits in sequence—likely reducing the speed at which merges land.
The Graphite Merge Queue is stack-aware, providing opportunities for faster concurrent/batched merges and optimizing the order in which PRs are merged. So if the stack is added to the queue together, the merge queue can process and validate the entire stack in parallel. No need for CI to run again since we have already validated the CI against that exact change (this is also known as fast-forward merge, as described below).
See our blog post to learn more about the benefits of merge queues.
Supported merge strategies
Rebase: rebase your changes on top of your trunk with commits unchanged (equivalent to GitHub's rebase and merge)
Squash: rebase your changes on top of your trunk with each PR squashed to a single commit (equivalent to GitHub's squash and merge)
Fast-forward merge: you can opt to enable "fast-forward merge" on either of the above strategies in order to process stacked PRs in parallel (a Graphite-only setting).
How the Graphite merge queue interacts with GitHub
In your repository settings, you have the option to enforce the Graphite merge queue. If it isn't enforced, users will be able to merge PRs through GitHub directly (bypassing the merge queue entirely). Enforcing the Graphite merge queue requires some configuration on GitHub's side, namely setting up the correct branch protection rules and authorizing with Graphite's GitHub App. Read more about advanced Graphite merge queue settings.
Warning
The Graphite merge queue is not compatible with GitHub's merge queue—if you want to use the Graphite merge queue and you're currently using GitHub's, you must disable it for your repository before continuing.
When a PR is added to the Graphite merge queue, we leave comments on your GitHub PR in three instances: when the PR is added to the queue, when it is merged through the queue, and when it fails/is removed from the queue.
External merge queue integration
If you already use a separate external merge queue offering, Graphite's external merge queue integration simplifies the merging experience. While it doesn't experience the same stack-aware optimizations as Graphite's merge queue, it can be a quick way to ramp-up your team. See external merge queue integration for more info.
