Queue Modes

The merge_queue.mode option controls how the merge queue schedules pull requests. There are three modes:

• serial (default) — every pull request is tested on top of the previous one, in a single ordered pipeline.

• parallel — pull requests that touch different scopes are tested and merged at the same time.

• isolated — every batch runs as a fully independent unit, with no dependency on any other batch.

All three honor your queue rules and batch sizing. They differ only in how batches depend on each other.

The rest of this page describes each mode in turn. Serial is the default, so if you do nothing you are already using it.

Serial mode is the default — you don’t need to configure anything to use it. Every pull request is tested on top of the one before it, forming a single ordered pipeline. This guarantees correctness: each pull request is validated against the exact state it will merge into. The trade-off is that unrelated changes still wait for each other.

Even though PR #3 (docs) has nothing in common with PR #1 (api) or PR #2 (frontend), it still waits behind them.

You can set it explicitly, though it is the default:

merge_queue:
  mode: serial

Serial mode still uses batches and parallel checks to increase throughput without giving up cumulative testing. If most of your pull requests touch the same files, serial mode is usually the right choice.

Parallel mode tests and merges pull requests that touch different areas of the codebase — different scopes — at the same time. Pull requests that share a scope are still queued together so they are tested as a group, preventing semantic conflicts.

Batches that share no scope run at the same time:

When scopes do overlap, Mergify preserves ordering within that scope to guarantee the changes are tested together:

Here PR #4 touches the api scope, just like PR #1 — so it must wait for PR #1 to merge first. Meanwhile PR #3 (docs) proceeds independently.

Parallel mode requires two things: configuring scopes so Mergify knows which areas of the codebase each pull request touches, and switching the mode.

Scopes can come from file patterns declared directly in .mergify.yml, or from an external build system (Nx, Bazel, Turborepo, …) via the gha-mergify-ci GitHub Action.

scopes:
  source:
    files:
      api:
        include:
          - services/api/**/*
      frontend:
        include:
          - apps/web/**/*
      docs:
        include:
          - docs/**/*

See Scopes for all configuration options and build-tool integrations.

Add mode: parallel under merge_queue:

merge_queue:
  mode: parallel
  max_parallel_checks: 5

scopes:
  source:
    files:
      api:
        include:
          - services/api/**/*
      frontend:
        include:
          - apps/web/**/*
      docs:
        include:
          - docs/**/*

queue_rules:
  - name: default
    batch_size: 3
    queue_conditions:
      - check-success = ci

The max_parallel_checks setting controls how many batches Mergify tests at the same time across all scope queues. Tune it to match your CI capacity.

Once parallel mode is active, the merge queue follows these steps whenever it processes pull requests:

1. Scope assignment. Each pull request is tagged with the scopes it affects, either automatically from file patterns or via an external upload.

2. Batch formation. Mergify groups pull requests that share exactly the same set of scopes into batches (respecting batch_size). Pull requests with different scopes form separate batches.

3. Dependency tracking. Batches that share at least one scope are linked as parent → child in a dependency graph. A child batch cannot merge until all its parents have merged.

4. Parallel execution. Batches with no shared scopes — and therefore no dependency — are tested by CI at the same time, up to max_parallel_checks.

5. Merge. As soon as a batch’s CI passes and all its parent batches are merged, Mergify merges the pull requests in that batch.

When a batch fails, Mergify splits it and retests the parts to isolate the problematic pull request (see Handling Batch Failures). Because batches are scoped, a failure in one scope queue does not block unrelated scope queues — only batches that depend on the failed one (via a shared scope) are affected.

max_parallel_checks caps how many speculative checks run at once across all scopes. Sometimes you want to bound a single scope on top of that: a scope whose tests are expensive or hit a shared resource that can’t take many concurrent runs (a staging environment or a rate-limited external service), while the rest of your scopes can use whatever capacity the global ceiling leaves them.

scopes.capacities maps a scope name to the number of speculative checks that scope may run at the same time:

merge_queue:
  mode: parallel
  max_parallel_checks: 5

scopes:
  source:
    files:
      frontend:
        include:
          - apps/web/**/*
      backend:
        include:
          - services/api/**/*
      docs:
        include:
          - docs/**/*
  capacities:
    frontend: 2
    backend: 2

Here frontend and backend are each limited to 2 concurrent speculative checks. docs is absent from the map, so it stays uncapped: only the global ceiling applies to it.

max_parallel_checks is the global ceiling: the most speculative checks a train will ever run at once. Each scopes.capacities entry is a sub-limit inside that ceiling, not an extra budget on top of it:

• A speculative check consumes one global slot and one slot in every capped scope its batch belongs to.

• It starts only when the global ceiling has room and each of its capped scopes has room.

• A scope that isn’t listed in capacities is unlimited; it draws on the global ceiling alone.

Because every check always takes a global slot, the total running at once never exceeds max_parallel_checks, whatever you put in capacities. Capacities can only ever hold a scope below the global ceiling; they never raise the total, so adding them to an existing configuration cannot increase your CI load.

Take the configuration above (max_parallel_checks: 5, frontend: 2, backend: 2, docs uncapped) and suppose the queue is ready to test three frontend batches, three backend batches, and two docs batches. The slots might fill like this:

• frontend and backend each run at most 2 batches, so each holds back its third; those wait for a free slot in their own scope.

• docs is uncapped, but only as many docs batches run as there is room under the ceiling of 5. Here that is 1, so the second docs batch waits, not because docs is capped (it isn’t) but because the global ceiling is full.

Two things always hold: no capped scope runs more than its limit, and no more than max_parallel_checks run at once. Exactly which batches fill the slots, and whether the last free slot goes to docs or to a capped scope still below its limit, follows queue order, so the split can differ from one cycle to the next. As soon as a running check finishes, its freed global slot (and its freed scope slot, if any) go to the next waiting batch that fits both.

A batch that touches more than one capped scope must fit in all of them at once. A batch carrying both frontend and backend consumes one frontend slot and one backend slot, and starts only when both scopes, and the global ceiling, have room. This keeps every scope’s limit honored even when changes span scopes.

capacities only sets the limit; it does not decide which pull requests belong to a scope. Membership comes from your scopes.source, so capacities behave the same whether scopes are derived from file patterns (source: files) or pushed from an external build system (source: manual). You declare the limit once, no matter how membership is computed.

Parallel mode is built for the reality of monorepos: most pull requests are independent, but some do interact.

The net effect: pull requests merge faster when their scopes don’t collide, while pull requests that do collide are still tested in the right order to avoid semantic conflicts reaching your main branch.

Parallel mode keeps dependencies between batches that share a scope. Isolated mode drops them entirely: every batch is a self-contained unit that is tested and merged on its own, with no parent batch and no child batch. A failure in one batch never blocks any other.

Use isolated mode when your pull requests are genuinely independent and you want maximum throughput without maintaining a scope map — for example when each pull request targets its own service or package and you don’t need Mergify to serialize overlapping changes.

Set mode: isolated under merge_queue. Unlike parallel mode, scopes are optional:

merge_queue:
  mode: isolated
  max_parallel_checks: 5

queue_rules:
  - name: default
    batch_size: 5
    queue_conditions:
      - check-success = ci

How Mergify fills a batch depends on whether you configure scopes:

• With scopes. Mergify groups the most similar pull requests — those sharing the most scopes — into the same batch, using the same scope-aware batching as the other modes. This keeps related changes tested together and maximizes CI reuse.

• Without scopes. Mergify fills batches by queue priority and arrival order, up to batch_size.

Either way, the resulting batches are fully independent. They run concurrently up to max_parallel_checks, and Mergify merges each one as soon as its own CI passes — there is never a parent batch to wait for. Batch failures are handled the same way as in the other modes (see Handling Batch Failures).

Parallel and isolated modes change how the queue operates. Some features that rely on strict single-queue ordering are not available:

• Scopes are required in parallel mode. You must configure scopes.source (either files or manual) so Mergify can tell which pull requests are independent. Serial and isolated modes do not require scopes.

• fast-forward merge is not supported. Because batches merge independently, Mergify needs to rebase them. Use merge or rebase as your merge_method.

• skip_intermediate_results is not available. This feature depends on the strict cumulative ordering of serial mode.

• partition_rules are not supported. Partitions rely on serial ordering; use scopes instead.

• Scopes: learn how to define and manage scopes for your repository.

• Batches: understand batch formation, sizing, and failure handling.

• Performance: tune your queue for the right balance of speed, cost, and reliability.

• Monorepo: broader guidance on using Mergify in monorepo setups.