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.

Graphite merge queue

You would likely benefit from a merge queue if:

• Your trunk branch is frequently broken

• You'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.

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.