Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.trunk.io/llms.txt

Use this file to discover all available pages before exploring further.

​
What it is

Trunk Merge Queue tests pull requests against the projected future state of your main branch, not just the current state. This means when multiple PRs are in the queue, each PR is tested as if all the PRs ahead of it have already been merged. This prevents “queue collapse” - where PRs pass tests individually but fail when merged together.

​
Why use it

Normally, pull requests are tested against a snapshot of the head of main when the pull request is posted to your source control provider. This can mean that by the time the pull request is actually merged - the results of the automated testing are stale. When you merge a pull request with stale results, you are effectively merging in un-tested code. The changes to the protected branch since the test was run create a blind spot in your testing regimen. With predictive testing, you no longer have a blind spot because the merge queue ensures that the pull request is tested against the state of main that will exist when your pull request is merged.

​
What’s Happening? The “Happy Path”

This example shows how pull requests (PRs) are tested in a queue. PR B is tested with the changes from A, and C is tested with the changes from both A and B.
What’s Happening?Queue
A begins testingmain <- A
B begins predictive testing by including the changes in Amain <- A <- B+a <- C+ba
C begins predictive testing by including the changes in both A and Bmain <- A <- B+a <- C+ba
as testing completes - pull requests can merge safelymerge A, B, C

​
The “Unhappy Path”: How the Queue Handles Test Failures

Predictive testing is effective, but it creates a new challenge: failure cascades. In the “Happy Path” example, if PR A introduces a failing test, the predictive tests for B and C are also guaranteed to fail, because they both include the broken code from A. A simple queue would kick B and C as soon as their tests failed. This would disrupt their authors, who did nothing wrong, and force them to restart their PRs multiple times, wasting valuable CI time . This is solved by Pending Failure.

​
How Pending Failure Works

The main purpose of “pending failure” is to minimize disruptions to the queue by intelligently finding the true source of a failure. Instead of immediately kicking a PR just because its test run failed, the queue follows this logic:
  1. A Test Fails: Let’s say PR C’s test run fails.
  2. Enter Pending Failure State: C is not kicked. It enters a Pending Failure state and waits for the PRs it depends on (A and B) to finish testing.
  3. Identify the Root Cause: The queue’s goal is to determine: “Did this PR fail because of its own code, or did it fail because of a change in a PR ahead of it?”.
    • C (failed) waits for B.
    • B (also fails) waits for A.
    • When A (at the top of the queue) fails, the queue knows it must be the PR that introduced the failure, as it only depends on main.
  4. Minimize Disruption: The queue only kicks the first faulty PR (A).
  5. Automatic Recovery: PRs B and C (which are likely healthy) stay in the queue. They are automatically re-scheduled for testing with a new predicted state that excludes the bad PR (e.g., B now tests against main, and C tests against main + B).
Pending Failure is the essential recovery mechanism that makes Predictive Testing practical. It ensures the queue is resilient and that engineers are not disrupted by test failures they didn’t cause.
The predecessor-waiting described above is built into the Pending Failure state and always happens. The Pending Failure Depth configuration adds an additional hold: it also waits for successor test runs to complete, which enables optimistic merging to automatically clear failures caused by flakes.