Merge Queue FAQ

Troubleshooting and FAQ

Can I add a pull request to the merge queue before all its required status checks have passed?

Yes. A pull request can be submitted to the queue at any time, even if it's not yet ready to merge. The pull request will enter the queue in a "Queued" state and wait for all branch protection rules (like passing status checks and required reviews) to be met. Once the PR is ready, Trunk Merge Queue will automatically move it into the testing phase.

Can I choose the merge strategy (e.g., squash, rebase, or merge commit) for my pull requests?

No, Trunk Merge Queue exclusively uses a squash merge for all pull requests. It is not currently possible to select a different merge strategy like rebase or a standard merge commit on a per-PR basis.

When a pull request is squash merged, how is the commit message determined?

The commit message for the squashed commit is automatically generated from the pull request's title and description, which is the default behavior provided by GitHub.

Do settings like "Optimistic Merging" or "Batching" cause multiple pull requests to be merged into a single commit?

No. Pull requests are always merged individually, and each PR will result in a separate commit in your main branch's history, regardless of your configuration.

Features like Optimistic Merging and Batching are validation and testing strategies, not merging strategies.

• Optimistic Merging uses the successful test of a pull request later in the queue to validate all the PRs ahead of it in the queue, allowing the entire sequence to be merged without waiting for the earlier PRs to finish testing.

• Batching allows the queue to test multiple PRs in a single CI job to save time and resources. After the test passes, the PRs in the batch are still merged one by one.

How am I notified if my pull request fails in the merge queue?

When a pull request is removed from the queue due to a failure, the Trunk bot updates its comment on the original PR. This update includes direct links to the specific workflows that failed, allowing you to quickly investigate and resolve the issue. Example below.

Can I create multiple merge queues for a single repository? For example, can I have a separate 'test' queue for validating CI changes?

Currently, Trunk Merge Queue supports one merge queue per repository. If this is critical for your use case, talk to us and we'll consider adding support for your use case.

For validating significant changes to your CI process or queue configuration without impacting your primary workflow, the recommended approach is to use a fork of your repository. You can set up and test a separate merge queue on the fork to ensure your changes work as expected before applying them to your primary repository.

My pull request is testing in my Merge Queue, but it doesn't look like my required status checks are being triggered.

Most likely, you did not set up the required status checks to trigger for trunk-merge/ branches. It is also possible that your CI provider just randomly never started testing on the Trunk Merge Queue branch, even after setting the required status checks to trigger. To assist with this, you can configure a testing timeout.

My pull request appears to be ready but isn't entering the Merge Queue.

First, check the Trunk web app to see what Trunk is waiting on before putting your PR into the merge queue.

Next, if something on that page doesn't look right, for example, it says that GitHub is still checking the mergeability of the PR, comment /trunk merge again in the PR.

My pull request is constantly failing when it starts testing because of "GitHub errors".

Most likely, you have a branch protection rule that affects merge branches. For example, the wild card rule */* applies to trunk-merge/.... The Trunk GitHub app does not have admin privileges, so it fails to do some actions on protected branches. To resolve this, you must remove this rule or reach out to Trunk on our community Slack if that is not possible.

My pull request is constantly failing when attempting to merge it

The two most likely problems are that you are restricting who can merge or that you have disabled squash merges into your repo. Trunk Merge Queue needs to use squash merges. To fix this, turn on 'allow squash merges' for this repo in your GitHub setup.

What is the purpose of trunk-temp/* branches, and should we configure our CI to run on them?

No, you should configure your CI to completely ignore trunk-temp/* branches. Running workflows on them will only create unnecessary or canceled builds.

The trunk-temp/* branch is a temporary, intermediate branch that the merge queue uses to assemble the necessary commits for a test run. Once the build is prepared, this branch is immediately renamed to a trunk-merge/* branch.

Why do Dependabot and Renovate pull requests keep getting kicked from the Merge Queue?

By default, both dependabot and renovate both will rebase their PRs whenever other PRs merge into their base branch. If that rebase happens when those PRs are in the queue, they will get kicked since they were updated. There are two ways to mitigate this:

1. Both dependabot and renovate can be configured to not automatically rebase, while renovate can specifically be configured to only rebase if there's a merge conflict (dependabot, renovate)

2. Their PRs can be manually merged, and anything currently in the merge queue will restart with those merged changes

I have an emergency pull request that needs to merge right now. How can I do that?

Recommended approach: Use PR Prioritization to fast-track your PR through the queue while still validating it:

/trunk merge --priority=urgent

The urgent priority is the only level that will interrupt currently testing PRs. Your PR will immediately begin testing, and other PRs will restart after yours completes.

Emergency bypass: If you need to completely bypass the merge queue, you can merge the PR directly through GitHub as you normally would. The merge queue will restart everything currently testing to account for the new head of the merge branch. However, this means your emergency PR won't be validated by the merge queue's predictive testing.