Graphite Merge Queue

Note

The Graphite Merge Queue (aka GTMQ) is currently in paid beta - it is enabled at the org-level. If your organization is interested in a live demo or getting access, email us at hello@graphite.dev.

What is the Graphite Merge Queue?

The Graphite Merge Queue, like other merge queues, increases velocity in software development by automating pull request merges into your trunk branch. Graphite's merge queue is stack-aware, providing opportunities for faster concurrent/batched merges and further reduction in CI costs.

How is it different than other merge queues?

One of the challenges of a typical merge queue is that it can slow down merging. Merge queues enforce the ordering of commits and validate those commits in sequence, likely slowing down the speed at which merges land.

The Graphite Merge Queue honors the dependencies between PRs in a stack (which is already ordered). So if the stack is added to the queue together, the merge queue can process and validate the entire stack in parallel.

This means that once the first PR in a stack merges, all the upstack PRs it was enqueued with should be almost ready to merge. 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, see below).

What merge strategies are supported?

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 does the Graphite Merge Queue interact 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 rather than OAuth - more docs coming on this soon.

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 cases: when the PR is added to the queue, when it is merged via the queue, and when it fails/is removed from the queue.