[TRUNK-17696] Document multiple queues per repository

merge-queue/administration/advanced-settings.md

@@ -105,6 +105,31 @@ The `Running` state is the default state of your merge queue, and will be the no
 
 ***
 
+## Multiple queues per repository
+
+You can create multiple merge queues within a single repository, with each queue targeting a different branch. This is useful for teams that maintain separate branches for different environments (e.g., `main`, `staging`, `release/v2`).
+
+A branch can only be associated with one queue. Attempting to create a second queue against the same branch returns the error `A merge queue already exists for branch "<branch>" in this repository`.
+
+Each queue operates independently. PRs submitted to one queue don't interact with PRs in another queue for the same repo, and every queue has its own settings, including merge method, required statuses, batching, and concurrency.
+
+### Creating additional queues
+
+1. Navigate to **Merge Queue** and click **New Queue** at the top right
+2. Select the same repository and enter a different target branch
+3. Click **Create Queue**
+
+### Navigating between queues
+
+The Merge Queue dashboard groups queues by repository:
+
+* **Single-queue repos**: The repository row is itself a link that goes directly to the queue.
+* **Multi-queue repos**: The repository row expands inline to list each queue with its target branch label. Click any queue to open it.
+
+In the Settings page, when a repository has more than one queue, a **Merge Queues** selector appears so you can switch between queues. The currently selected branch is shown next to the **Merge Queue Settings** heading.
+
+***
+
 ## Merge Queue mode
 
 > Merge Queues operate in one of two modes, **Single** (default) or [**Parallel**](../optimizations/parallel-queues/)**.**

merge-queue/getting-started/install-and-create-your-queue.md

@@ -50,6 +50,10 @@ If the GitHub App is already installed, step 3 will be skipped automatically.
 
 You've installed the Trunk GitHub App on your organization and created your first merge queue for the specified branch (`main` in the example above). Trunk is now connected to your repository and ready to be configured. Your queue won't start processing pull requests until you complete the branch protection setup in the next step.
 
+{% hint style="info" %}
+**Need multiple queues?** You can create additional queues for the same repository targeting different branches (e.g., `staging`, `release/v2`). Each queue operates independently with its own settings. See [Multiple queues per repository](../administration/advanced-settings.md#multiple-queues-per-repository) for details.
+{% endhint %}
+
 ### Next steps
 
 → [**Configure branch protection**](configure-branch-protection.md) - Set up GitHub rules so Trunk can safely manage your merges

merge-queue/reference/common-problems.md

@@ -87,9 +87,11 @@ Features like Optimistic Merging and Batching are validation and testing strateg
 
 <summary>Can I create multiple merge queues for a single repository?</summary>
 
-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! 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.
 
-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 make sure your changes work as expected before applying them to your primary repository.
+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](../administration/advanced-settings.md#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.
 
 </details>