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
- PR #1 enters the queue and tests against
main. - PR #2 enters and tests against
main + #1, assuming #1 will pass. - 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 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 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 (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.