For the fourth day of launch week, we wanted to stay with the theme of shipping top asks from our largest and fastest-moving Graphite customers. Many of these most productive teams use Graphite’s merge queue to automate and speed up their merge process while keeping their trunk branches green. Today we’re excited to announce one of our most highly-requested merge queue features: batch merging.

Batching enables higher throughput and lower CI costs

As your team starts using a merge queue to keep your trunk branch green and/or merge stacks faster, it’s important to make sure your queue doesn’t slow down your releases or balloon your CI costs.

Batching is a workflow where the merge queue groups several to-be-merged PRs together into a temporary combined PR, runs CI on it, and then merges all of them together if everything passes. If something goes wrong, the merge queue can bisect the batch and help you find the breaking change.

Batching is an effective strategy for both handling a higher volume of PRs and reducing CI spend. You can customize the batch size for each repo depending on your desired throughput.

Picking the right merge strategy for your repo

We previously shipped Parallel CI to also increase merge queue throughput, and have seen customers able to reduce their merge times to approximately equal the time it takes to run CI on a single pull request. Parallel CI also ensures every PR and stack individually passes CI, ensuring that every commit on main is “green” and safe to revert to.

Batch merging takes a different approach: relaxing the requirement for correctness on every single commit in the batch in favor of reducing overall CI runs (and costs) and enabling more throughput. Batching still ensures that all tests are passing at head on your trunk branch after the batch merges, but you shouldn’t turn on batching if you require every single commit in history to build correctly. However, for most fast-moving teams, trading off perfect revert-ability for significantly faster queue times and lower CI costs is worthwhile.

How batch merging works

Batch merging relies heavily on two concepts: draft PRs and fast-forward merge. Imagine you have five stacks queued to merge, and your batch size is four (configurable in your merge queue settings):

1. The Graphite merge queue will create a single draft PR that contains stack #4 rebased onto stack #3 rebased onto stack #2, which is finally rebased onto stack #1.

2. Once we create this draft PR, the merge queue now waits for CI to run on it.

3. ✅ If CI passes, the merge queue will simply update main to point to the HEAD commit hash of this draft PR (performing a fast-forward merge). Fast forward merge is great because it allows us to merge several PRs into main in a single operation. We simply update main to be the commit hash for the draft PR.

4. ❌ If CI fails, keep on reading…

What happens when there is an error in a batch?

The Graphite merge queue has two options for what to do when a batch fails CI:

1. Remove the entire batch from the queue and have PR authors isolate the issue and re-queue their PRs.

2. Bisect and find the culprit PR/stack, and add every other PR/stack in the batch back to to the queue (coming soon).

Getting started with merge queue batching

Merge queue batching is currently in public beta. Enable it in your merge queue settings!