Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 19 additions & 9 deletions src/content/docs/merge-queue/parallel-checks.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,26 @@ description: Accelerates the merging process by testing the compatibility of mul
import { Image } from "astro:assets"
import specChecksListScreenshot from "../../images/merge-queue/parallel-checks/spec-checks-list.png"

Parallel Checks let Mergify test multiple queued pull requests together so you
ship faster. Mergify creates temporary batch PRs that represent cumulative
merges (PR#1), (PR#1+PR#2), (PR#1+PR#2+PR#3), runs CI on them in parallel, then
merges the original PRs once checks pass.
Parallel checks are how Mergify tests the queue **speculatively**: instead of
validating one pull request at a time, it tests several queued pull requests
ahead of time so you ship faster. Mergify creates temporary batch PRs that
represent cumulative merges (PR#1), (PR#1+PR#2), (PR#1+PR#2+PR#3), runs CI on
them in parallel, then merges the original PRs once checks pass. The
`max_parallel_checks` setting controls how far ahead it tests.

:::tip
Learn how speculative checks work conceptually at the
[Merge Queue Academy](https://merge-queue.academy/features/speculative-merging/).
:::

:::note
Parallel checks are not the same as **parallel mode**. Parallel checks are
speculative CI that speed up any single ordered queue, in serial or parallel
mode alike. [Parallel mode](/merge-queue/queue-modes) is a separate choice
about whether independent [scopes](/merge-queue/scopes) form independent
queues. The two are configured separately and work together.
:::

## How Parallel Checks Work

Mergify groups PRs by their position in the queue and the `max_parallel_checks`
Expand Down Expand Up @@ -126,7 +136,7 @@ to match your CI capacity and typical PR size/complexity.

## When Things Change

Parallel Checks adapt automatically as your code and rules evolve:
Parallel checks adapt automatically as your code and rules evolve:

- Failed checks: Mergify removes the failing PR and continues with the rest.

Expand Down Expand Up @@ -246,7 +256,7 @@ increase concurrency; choose a value your CI can handle reliably. For deeper
guidance and trade‑offs (including batching), see [Merge queue
performance](/merge-queue/performance).

In [parallel mode](/merge-queue/parallel-scopes), you can also cap concurrency
for an individual scope while leaving the rest free to use the global ceiling.
See [Limiting concurrency per
scope](/merge-queue/parallel-scopes#limiting-concurrency-per-scope).
In [parallel mode](/merge-queue/queue-modes#parallel-mode), you can also cap
concurrency for an individual scope while leaving the rest free to use the
global ceiling. See [Limiting concurrency per
scope](/merge-queue/queue-modes#limiting-concurrency-per-scope).
7 changes: 7 additions & 0 deletions src/content/docs/merge-queue/queue-modes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,13 @@ together so they are tested as a group, preventing semantic conflicts.
serial mode may be a better fit.
:::

:::note
Parallel **mode** is not the same as [parallel checks](/merge-queue/parallel-checks). Parallel
mode is about **scopes**: independent queues that don't wait on each other. Parallel checks are
**speculative** CI that test queued pull requests ahead of time within a single ordered queue,
and they run in serial mode too. The two are configured separately and work together.
:::

Batches that share no scope run at the same time:

```dot class="graph"
Expand Down