FAQ
Troubleshooting and FAQ
Entering the Queue
Can I add a pull request to the queue before all required checks pass?
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.
Why isn’t my pull request entering the 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.
Why aren't my required checks triggering, even though my pull request is being tested in queue?
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.
Merge Behavior
Can I choose the merge strategy 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.
How is the squash-merge 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 Optimistic Merging or Batching ever merge multiple pull requests 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.
Queue Configuration
Can I create multiple merge queues for a single repository?
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.
What are trunk-temp/* branches, and should CI 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.
Priority & Overrides
How can I merge a pull request immediately?
Recommended approach: Use PR Prioritization to fast-track your PR through the queue while still validating it:
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.
How do I merge an emergency pull request right now?
Recommended approach: Use PR Prioritization to fast-track your PR through the queue while still validating it:
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.
Failures, Errors & Debugging
How am I notified if my pull request fails in the 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.
Why does my pull request consistently fail during testing due to "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.
Why does my pull request keep failing to merge in the queue?
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.
Why do Dependabot and Renovate pull requests keep getting kicked from the 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:
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)
Their PRs can be manually merged, and anything currently in the merge queue will restart with those merged changes
Last updated