---
title: "Speculative Checks in a Merge Queue"
description: "Speculative checks parallelize merge queue testing by assuming PRs ahead in the queue will pass. The result is a queue that runs in parallel rather than serially, cutting latency from hours to minutes when failure rates are low."
url: https://mergify.com/learn/merge-queue/speculative-merging
---

[← Back to merge queue guide](https://mergify.com/learn/merge-queue)Merge queue feature

# Speculative checks

A serial merge queue tests one PR at a time, each waiting for the previous one to finish. Speculative checks let the queue test multiple PRs in parallel by assuming earlier PRs will pass.

gantt
    title 3 PRs through the queue (30-min CI each)
    dateFormat X
    axisFormat %M min

    section Sequential
    PR #1 (vs main)              :s1, 0, 30
    PR #2 (vs main + #1)         :s2, after s1, 30
    PR #3 (vs main + #1 + #2)    :s3, after s2, 30

    section Speculative
    PR #1 (vs main)              :p1, 0, 30
    PR #2 (vs main + #1)         :p2, 0, 30
    PR #3 (vs main + #1 + #2)    :p3, 0, 30

Same correctness, three times faster when the speculation holds.

## Sequential vs speculative

With a serial queue and a 30-minute CI pipeline, three PRs take 90 minutes to clear. Each waits for the one before it.

| PR | Sequential start | Sequential finish | Speculative finish |
| --- | --- | --- | --- |
| #1 (vs main) | 0 min | 30 min | 30 min |
| #2 (vs main + #1) | 30 min | 60 min | 30 min |
| #3 (vs main + #1 + #2) | 60 min | 90 min | 30 min |

With speculative checks, all three test in parallel against their predicted future bases. Three times faster, same correctness guarantees if the speculation holds.

## How it works

1.  PR #1 enters the queue and tests against `main`.
2.  PR #2 enters and tests against `main + #1`, assuming #1 will pass.
3.  PR #3 enters and tests against `main + #1 + #2`, assuming both will pass.

All three tests run simultaneously. If the speculation holds, you got the work of three sequential CI runs in the time of one.

## When speculation is wrong

If PR #1 fails, the speculation for PRs #2 and #3 was wrong. They were tested against a state that will never exist. The queue removes #1, re-bases the others, and re-runs CI. The wasted work is the time of one CI run, which on average is still much faster than running everything sequentially.

This is also why a failure early in the queue costs more than a failure late in the queue. If PR #1 fails, every speculation behind it is invalidated. If PR #3 fails, only PR #4 needs to restart. Hence why [two-step CI](https://mergify.com/learn/merge-queue/two-step-ci) matters: catching obvious failures on the PR itself, before the speculative work begins, avoids the expensive cascade.

## Speculation depth

You can cap how far ahead the queue speculates. The right depth depends on your queue failure rate.

| Depth | Behavior |
| --- | --- |
| 1 | No speculation. Sequential queue. |
| 3 | Up to 3 PRs in flight at once. |
| Unlimited | Test the entire queue in parallel. |

Higher depth means more parallelism but more wasted CI when early PRs fail. A useful metric to track is speculation hit rate, the percentage of speculative runs that did not need to restart. If your hit rate drops below 80%, dial depth down or fix your test stability before it becomes a CI bill.

## Combining with batching

[Batching](https://mergify.com/learn/merge-queue/batching) and speculative checks compose well. Speculatively test batch \[1-3\] and batch \[4-6\] in parallel, and you get the speed of speculation with the cost efficiency of batching.

## Best for

-   Teams with high PR volume.
-   Codebases with stable tests and low queue failure rates.

See [how to enable speculative checks in Mergify](https://docs.mergify.com/merge-queue/queue/) (set `speculative_checks` on a queue rule).

## Stop merging serially.

Mergify runs speculative queue CI by default. You set the depth, we run them in parallel and recover automatically when a speculation breaks.

[See the product](https://mergify.com/product/merge-queue)[Talk to our team](https://mergify.com/discovery)
