Setup

How to set up Trunk Merge Queue for your project

Minimal set up is required to get started with Trunk Merge Queue, as it syncs with GitHub in order to run the same tests you're already running on PRs and require the same Status Checks to pass before merging.

Connect your Trunk Organization to GitHub

Sign up at app.trunk.io, create a Trunk organization, and connect it to your GitHub repositories. If your repository is already connected to your Trunk organization, you can skip this step.

Select the repository you would like to use and click Get Started.

Set Up Trunk Merge Queue

Go to the Merge tab. You will see the "Set Up Trunk Merge Queue" page. From there, you can specify:

1. The name of the branch that Trunk Merge Queue should help manage merging PRs into.

2. The number of Pull Requests that Merge can test at the same time.
3. The mode that Trunk Merge Queue Queues will start in.

Testing PRs In the Queue

Trunk will automatically create Draft PRs when PRs begin testing in the queue. The draft PR will contain the tip of the branch you're merging into, the change in the PR, and changes in any PRs in front of this one in the queue

By using draft PRs, Trunk will leverage your existing status checks that gate your PRs already with tests and linters. When the new draft PRs are created, Trunk will wait for your existing status checks to run, and merge PRs when they pass.

If you do not want every check that runs when a PR is opened to also run when Trunk Merge Queue tests PRs, you can disable draft PR creation and run tests on branches instead. See Draft PRs.

Trunk Merge Queue syncs with GitHub's branch protection rules, and will require the same status checks that need to pass in order to merge a PR to also pass when testing the PR in the queue.

Submit Pull Requests

Try making a simple change on a branch and submit it as PR in GitHub.

Now trigger Trunk Merge Queue to process this PR using either a comment on the PR in GitHub or using the Trunk CLI.

GitHub Pull Request View

Comment /trunk merge on a pull request

Trunk CLI

# Authenticate with trunk service
$ trunk login
# Queue pull request for merge
$ trunk merge {pr-number}

If you have any problems with merge queueing PRs, take a look at the branch protection docs.

Pull Request Processing

Once a PR is submitted to the Merge queue, it will start as Not Ready until all of the required conditions to submit it are met. Once ready, the Merge Queue will pick it up and run the tests. Once the tests pass, the PR may still need to wait for upstream PRs in the queue to finish their testing. Once the remaining upstream PRs are complete, the PR will be merged and then removed from the Merge Queue. If a PR fails or is canceled then it will go to the failed or canceled state. Read more about PR States.

Success!

Now Trunk Merge Queue is setup with your repo. Whenever a PR is pushed to your merge branch it will be safely tested and automatically merged when all tests pass, regardless of the order they were pushed in.

Next Steps

Now that you have the Merge Queue setup and running you can explore the knobs you can enable that will give you the most performant Merge solution. Explore the features powering Trunk Merge Queue here:

Batching

Dynamic Parallel Queues

Optimistic Merging

Pending Failure Depth

Prioritization

Flaky Test Protection