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?

Yes! Trunk Merge Queue supports three merge methods:

• Squash (default) - Combines all commits into a single commit
• Merge Commit - Preserves all individual commits and creates a merge commit
• Rebase - Replays commits on top of main for a linear history

The merge method is configured at the repository level in Settings > Repositories > [your repository] > Merge Queue. All PRs merged through the queue will use the selected method.

Note: The merge method applies to the entire repository, not on a per-PR basis. See Merge Method documentation for detailed information on each option and how to configure your preference.

How does Trunk handle commit messages

Commit messages depend on your configured merge method:

• Squash (default): The commit message is automatically generated from the pull request’s title and description, following GitHub’s default behavior
• Merge Commit: Preserves all individual commit messages from the PR and creates an additional merge commit message
• Rebase: Preserves all individual commit messages from the PR as they are replayed onto the target branch

You can override the merge commit title for any PR by adding merge-commit-title: Your Custom Title on its own line in the PR body. See Custom merge commit titles for details.

You can configure your preferred merge method in Advanced Settings.

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?

Yes! You can create multiple queues within a single repository, with each queue targeting a different branch (e.g., main, staging, release/v2). Each queue operates independently with its own settings, required statuses, and merge behavior. A branch can only be associated with one queue.

To create an additional queue, click New Queue from the Merge Queue dashboard and select the same repository with a different target branch. See Multiple queues per repository for details.

For validating significant changes to your CI process or queue configuration without impacting your primary workflow, you can use a fork of your repository. Set up and test a separate merge queue on the fork to make sure 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:

/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.

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:

/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.

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:

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