Batching

Learn the nuances of batching and related FAQs. Batching works alongside Parallel mode to scale the throughput of PRs merged, by merging more PRs per CI run.

Batching works alongside Parallel mode to increase the throughput of PRs merged, by merging more PRs per CI run.

How it works

Config Settings

There are two settings to set in your configuration file.

batch_size = This is the number of queued PRs batched together for a draft PR CI run. Defaults to 1.

batch_max_wait_minutes= The time to wait before creating the next batch of PRs, e.g. if batch_size = 3 but there are only currently 2 queued PRs, then a batch of those 2 PRs will be created after batch_max_wait_minutes. Defaults to 0.

version: 1.0.0
merge_rules:  
    labels:    
        trigger: "label_name"
    merge_mode:
        type: "parallel"
        parallel_mode:
            batch_size: 3
            batch_max_wait_minutes: 0

Current workflow

Here is the current workflow of parallel mode. It defaults to batch_size=1 since each additional CI pipeline will combine the changes from 1 PR and all the previous PRs in the queue.

Workflow with batch_size=1.

Workflow with batching

By adjusting batch_size, your repo can merge PRs faster with reduced CI runs. Let’s look at an example where batch_size=3 and we have 6 total tagged PRs.

Pipeline #1 will batch together the changes from PR#1, PR#2, and PR#3. Once the CI passes, PRs 1-3 will be merged.

Pipeline #2 will batch together the changes from Pipeline #1 and PR#4, PR#5, and PR#6. Once the CI passes, PRs 4-6 will be merged.

Workflow with batch_size=3.

By increasing the batch_size from 1 to 3, we can merge 6 PRs vs 2 PRs in the same time it takes to run 2 CI pipelines.

Here’s a quick comparison of how many additional CI pipelines* are run with different batch sizes for a queue with 10 PRs.

*Additional CI pipelines are the CI runs in addition to the CI that runs on the original PR.

	batch_size = 1	batch_size = 3	batch_size = 5
Additional CI Pipelines	10	4	2

Handling Failures

Bisection

It's inevitable that we will run into build failures - we handle this by requeuing PRs into bisected batches.

For example, let's say our batch_size=5 and we have PRs #1-5 in a single batch, with the corresponding draft PR #6.

If the draft PR fails, then we will close draft PR #6, and requeue all of PRs #1-5. These PRs will be put into two bisected batches - the first batch contains PRs #1-3, the second batch contains PRs #4-5.

Bisection if draft PR fails.

If a PR in the batch fails, we similarly requeue with bisection. In the above example, if PR #1 fails, then we block PR #1 and requeue PRs #2-5. Those PRs will be requeued into two batches - PRs #2-3 in one batch, PRs #4-5 in the other.

Other FAQs

How do you handle PRs with a skip_label?

All PRs with skip labels will be prioritized. They will be bumped to the top of the queue and will always be in its own batch. PRs with a skip_label will never be batched with other PRs.

What happens if I dequeue a PR?

The corresponding draft PRs as well as any subsequent draft PRs will be closed. PRs in the current batch will be requeued.

What happens if I add a new commit?

If you add a new commit to a PR, the associated draft PR will be closed and all subsequent draft PRs will be reset. The PRs in the batch will be automatically requeued.

What happens if my PR fails to merge but other PRs in the batch succeed?

If your PR fails to merge, we will automatically retry merging again. If it still fails, the PR will be blocked and may require manual changes.

What happens if I close the draft PR associated with multiple PRs?

If you manually close a draft PR, this will trigger a full reset of the queue. All draft PRs will be closed, and all PRs will be requeued.

What happens if I close my PR?

If you manually close a PR that has been queued and has an associated draft PR, this will trigger a full reset of the queue. All draft PRs will be closed and all PRs are requeued.