From 4b7fac4ed6a5883c6ee55e57214289697a5ff871 Mon Sep 17 00:00:00 2001 From: Julien Danjou Date: Tue, 16 Jun 2026 13:48:05 +0200 Subject: [PATCH] docs(merge-queue): document dynamic batch sizing batch_size now accepts a {min, max} range in addition to a fixed integer. Add a "Dynamic Batch Sizing" section to the batches page explaining how Mergify adapts the batch size to load, and a cross-linked subsection on the performance page positioning it as automatic batch-size tuning. MRGFY-7652 Co-Authored-By: Claude Opus 4.8 (1M context) Change-Id: I4548091d73a3232ac7203713b191dd6323eacf9a --- src/content/docs/merge-queue/batches.mdx | 37 ++++++++++++++++++++ src/content/docs/merge-queue/performance.mdx | 20 +++++++++++ 2 files changed, 57 insertions(+) diff --git a/src/content/docs/merge-queue/batches.mdx b/src/content/docs/merge-queue/batches.mdx index 70068f8ca0..f6595c0cf7 100644 --- a/src/content/docs/merge-queue/batches.mdx +++ b/src/content/docs/merge-queue/batches.mdx @@ -125,6 +125,43 @@ With the configuration above, Mergify waits up to 5 minutes for 5 PR to enter the queue before creating a batch. This allows you to pick the right trade-off between latency and minimal CI usage. +## Dynamic Batch Sizing + +The examples above use a fixed `batch_size`: every batch holds the same number of +pull requests. Picking that number is a trade-off. Small batches keep latency low +and make failures cheap to isolate, but spend more CI. Large batches conserve CI +and clear a backlog faster, but a single failure forces Mergify to [split and +retest](#handling-batch-failure-or-timeout) more pull requests. + +Dynamic batch sizing lets Mergify make that trade-off for you, in real time. +Instead of a single integer, set `batch_size` to a `min` and `max` range: + +```yaml +queue_rules: + - name: default + batch_size: + min: 1 + max: 10 +``` + +Mergify then spreads the queued pull requests across the available +[parallel checks](/merge-queue/performance#parallel-checks) and sizes each batch +to stay small while keeping up with the queue: + +- When the queue is light, batches stay at `min`, so each one is fast to validate + and cheap to split when it fails. + +- When the queue grows deeper than the parallel checks can drain at the smaller + size, Mergify grows the batches toward `max` to keep the queue moving. + +For example, with `max_parallel_checks: 5` and a `batch_size` range of `min: 1` +to `max: 2`, three queued pull requests each become a batch of one, while ten +queued pull requests become five batches of two. + +This gives low latency when traffic is light and high throughput when it spikes, +without retuning `batch_size` for every load pattern. Dynamic batch sizing works +the same way in every [queue mode](/merge-queue/queue-modes). + ## How Pull Requests Are Grouped Into a Batch When `batch_size` is greater than 1, Mergify has to decide *which* pull requests diff --git a/src/content/docs/merge-queue/performance.mdx b/src/content/docs/merge-queue/performance.mdx index 78359d68e9..3224f19347 100644 --- a/src/content/docs/merge-queue/performance.mdx +++ b/src/content/docs/merge-queue/performance.mdx @@ -88,6 +88,26 @@ Weigh these factors when picking `batch_size` and `max_parallel_checks`: 5. **Team distribution**: globally distributed teams produce a steady PR flow; concentrated teams spike and need headroom for bursts. +### Letting Mergify Tune Batch Size Automatically + +The factors above help you pick a fixed `batch_size`, but the ideal value shifts +with load: small batches are best when the queue is quiet, larger ones when it +backs up. Instead of committing to one number, give `batch_size` a range and let +Mergify adapt it in real time: + +```yaml +queue_rules: + - name: default + batch_size: + min: 1 + max: 10 +``` + +Mergify spreads the queued pull requests across the available [parallel +checks](#parallel-checks), keeping batches at `min` while the queue is light and +growing them toward `max` only when it backs up. See [Dynamic Batch +Sizing](/merge-queue/batches#dynamic-batch-sizing) for details. + ### Performance Configuration Calculator Provide the inputs below and the calculator will suggest a configuration: