diff --git a/merge-queue/administration/advanced-settings.md b/merge-queue/administration/advanced-settings.md index d34c6e8c..f1919341 100644 --- a/merge-queue/administration/advanced-settings.md +++ b/merge-queue/administration/advanced-settings.md @@ -328,6 +328,6 @@ This setting will delete the Merge Queue configuration and any queued merge requ **When to use this:** -* **Switching target branches** - If you need to change which branch the queue merges into (e.g., switching from a test branch during POC to `main` for production use), you must delete the current queue and create a new one pointing to your desired branch. +* **Switching target branches** - If you need to change which branch an existing queue merges into, you must delete the current queue and create a new one pointing to your desired branch. Note that you can also [create additional queues](../using-the-queue/multi-branch-queues.md) for other branches without deleting the existing one. * **Removing Merge Queue** - You're decommissioning Merge Queue for this repository entirely. * **Starting fresh** - You want to reset all configuration. diff --git a/merge-queue/reference/common-problems.md b/merge-queue/reference/common-problems.md index 662e1612..cefb9131 100644 --- a/merge-queue/reference/common-problems.md +++ b/merge-queue/reference/common-problems.md @@ -85,9 +85,21 @@ Features like Optimistic Merging and Batching are validation and testing strateg 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](../../setup-and-administration/support.md) and we'll consider adding support for your use case. +Yes. Trunk Merge Queue supports multiple queues per repository, each targeting a different branch. For example, you can run one queue merging into `main` and another merging into `release/v2`. Each queue operates independently with its own configuration, concurrency settings, and queue state. -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. +To create an additional queue for your repository: + +1. Navigate to the **Merge Queue** tab in [app.trunk.io](https://app.trunk.io). +2. Click **Create New Queue**. +3. Select the same repository and enter a different target branch. + +Each queue has its own settings (merge method, concurrency, batching, parallel mode, etc.) and can be managed independently. PRs are automatically routed to the correct queue based on their target branch. + +For more details, see [Multi-branch merge queues](../using-the-queue/multi-branch-queues.md). + +{% hint style="info" %} +**One queue per branch.** You can have multiple queues in the same repository, but each target branch can only have one queue. For example, you cannot create two separate queues that both merge into `main`. +{% endhint %} diff --git a/merge-queue/using-the-queue/multi-branch-queues.md b/merge-queue/using-the-queue/multi-branch-queues.md new file mode 100644 index 00000000..0b399b80 --- /dev/null +++ b/merge-queue/using-the-queue/multi-branch-queues.md @@ -0,0 +1,83 @@ +--- +description: >- + Run independent merge queues on different branches in the same repository. +--- + +# Multi-branch merge queues + +Trunk Merge Queue supports running multiple independent queues in a single repository, each targeting a different branch. This is useful for teams that maintain multiple long-lived branches, such as `main` and `release/*` branches, or `develop` and `staging`. + +## How it works + +Each merge queue is associated with a specific target branch in your repository. When you create a queue, you select a repository and a target branch. You can create additional queues for the same repository by selecting different target branches. + +PRs are automatically routed to the correct queue based on their target branch in GitHub. A PR targeting `main` enters the `main` queue, and a PR targeting `release/v2` enters the `release/v2` queue. Each queue: + +- Operates independently with its own position ordering +- Has its own configuration (concurrency, batching, parallel mode, merge method, etc.) +- Can be paused, drained, or running independently of other queues +- Creates its own `trunk-merge/*` test branches +- Reports status independently in the Trunk dashboard + +## Setting up multiple queues + +### Prerequisites + +Before creating an additional queue, make sure: + +- The Trunk GitHub App is already installed on the repository +- The target branch exists in your repository +- You have admin access to your Trunk organization + +### Create an additional queue + +1. Navigate to the **Merge Queue** tab in [app.trunk.io](https://app.trunk.io). +2. Click the **Create New Queue** button. +3. Select your repository from the dropdown. +4. Enter the target branch for the new queue (e.g., `release/v2`). +5. Click **Create Queue**. + +### Configure branch protection for each target branch + +Each target branch needs its own branch protection configuration. Follow the [Configure branch protection](../getting-started/configure-branch-protection.md) guide for each branch you are protecting with a merge queue. Specifically: + +- Add the `trunk-io` bot to the push restriction list for each target branch +- Ensure `trunk-temp/*` and `trunk-merge/*` branches are excluded from any wildcard branch protection rules + +### Configure CI for each queue + +Your CI workflows need to run on `trunk-merge/*` branches (or draft PRs, if using the default mode) regardless of which queue triggered them. If you use push-triggered mode, confirm your CI triggers cover branches created by all queues. + +## Common use cases + +### Release branches + +Maintain a queue on `main` for ongoing development and separate queues on `release/*` branches for cherry-picked hotfixes. Each queue validates changes independently, preventing broken releases. + +### Environment branches + +Teams that deploy from specific branches (e.g., `staging`, `production`) can protect each environment branch with its own queue, ensuring changes are validated before reaching each environment. + +### Monorepo with multiple deploy targets + +In a monorepo where different branches correspond to different deployment targets, each branch can have its own queue with tailored concurrency and batching settings. + +## Managing multiple queues + +### Dashboard + +Each queue appears separately in the Merge Queue tab of the Trunk dashboard. Select the repository, then choose the target branch to view and manage a specific queue. + +### CLI + +The Trunk CLI automatically detects the correct queue based on the PR's target branch. Commands like `trunk merge ` route to the appropriate queue without any additional flags. + +### API + +When using the [Merge Queue API](../reference/merge.md), specify the `targetBranch` field in your requests to interact with a specific queue. For example, the `createQueue` endpoint requires both `repo` and `targetBranch`. + +## Limitations + +- Each target branch can have at most one queue. You cannot create two queues for the same branch. +- Queue settings are independent. There is no way to share or inherit configuration between queues in the same repository. +- Each queue consumes its own concurrency slots. If you have two queues each set to a concurrency of 5, up to 10 PRs may be testing simultaneously across both queues. diff --git a/summary.md b/summary.md index 89ef27cb..becd7cc9 100644 --- a/summary.md +++ b/summary.md @@ -31,6 +31,7 @@ * [Handle failed pull requests](merge-queue/using-the-queue/handle-failed-pull-requests.md) * [Work with stacked pull requests](merge-queue/using-the-queue/stacked-pull-requests.md) * [Emergency pull requests](merge-queue/using-the-queue/emergency-pull-requests.md) + * [Multi-branch merge queues](merge-queue/using-the-queue/multi-branch-queues.md) * [Slack Integration](merge-queue/integration-for-slack.md) * [Webhooks](merge-queue/webhooks.md) * [Administration](merge-queue/administration/README.md)