[TRUNK-17696] Document multiple queues per repository

merge-queue/administration/advanced-settings.md

@@ -105,6 +105,29 @@ 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, each targeting a different branch. This is useful for teams that maintain separate branches for different environments (e.g., `main`, `staging`, `release/v2`).
+
+Each queue operates independently — PRs submitted to one queue don't interact with PRs in another queue for the same repo. Every queue has its own settings, including merge method, required statuses, batching, and concurrency.
+
+### Creating additional queues
+
+1. Navigate to **Merge Queue** and click **Create 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**: Appear as a clickable row that goes directly to the queue
+* **Multi-queue repos**: Expand to show each queue with its target branch label
+
+In the Settings page, use the branch selector at the top to switch between queues within a repo.
+
+***
+
 ## 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

@@ -44,6 +44,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

@@ -85,9 +85,9 @@ 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, each targeting a different branch (e.g., `main`, `staging`, `release/v2`). Each queue operates independently with its own settings, required statuses, and merge behavior.
 
-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, click **Create 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.
 
 </details>