[TRUNK-17696] Document multiple queues per repository#459
[TRUNK-17696] Document multiple queues per repository#459trunk-staging-io[bot] merged 4 commits intomainfrom
Conversation
|
😎 Merged successfully - details. |
samgutentag
changed the title
Add docs for creating multiple merge queues targeting different branches within the same repo. New section in advanced settings, updated FAQ, and hint in getting started guide. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
samgutentag
force-pushed
the
sam-gutentag/multiple-queues-per-repo
branch
from
fd8a10e to
f418177
Compare
|
Triage status (2026-05-05): merge conflicts with main in 3 merge-queue admin/getting-started files. Three open questions in the PR body also need engineering input before merge. |
|
Verification status (2026-05-06, re-verified): Verified: customers can use this. Ready to publish.
Two independent "delete legacy" rollout signals. The feature is unconditionally on in prod. Merge readiness:
Suggested next action: resolve conflicts, close out the open questions, then merge. |
Surface the unique-branch-per-queue rule in both the advanced settings section and the FAQ. The backend enforces it via the MERGE_INSTANCE_ALREADY_EXISTS error and customers searching for the error string should land on the docs. Also drops an em-dash in the advanced settings paragraph. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Resolves conflict in common-problems.md by keeping both the new multi-queue answer and the fork-based CI testing paragraph that the PR body says was retained. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Verified against trunk2: - Top-right button is "New Queue", not "Create New Queue" (page.tsx:56, merge-queue-settings-client.tsx:108). "Create New Queue" is only the empty-state button (merge-instances-list-empty.tsx:21). - Multi-queue rows are not collapsed by default — they always render inline. The Collapsible wrapper only applies to inactive-only repos (repository-queue-group.tsx:40). - Settings selector is labeled "Merge Queues" and only appears when availableQueues.length > 1 (merge-queue-settings-client.tsx:138). The selected branch shows as a chip next to the section title. - The actual error string from the create form is `A merge queue already exists for branch "<branch>" in this repository` (create-merge-client.tsx:95), not the simpler service-layer string. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Claude finished @samgutentag's task in 2m 39s —— View job Review summaryReviewed the three changed files for typos, grammar, formatting, and doc best practices. The new section is well-scoped and the cross-links resolve correctly. No blocking issues — just style/consistency nits, posted as inline suggestions.
Findings
What I checked and didn't flag
RecommendationAddress the button-label inconsistency before merge — it's the only finding likely to confuse a reader hunting for the button in the UI. The rest are polish. I couldn't run |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
|
|
||
| ### Creating additional queues | ||
|
|
||
| 1. Navigate to **Merge Queue** and click **New Queue** at the top right |
There was a problem hiding this comment.
Button label inconsistency. The other Merge Queue docs refer to this button as Create New Queue (e.g., install-and-create-your-queue.md lines 27 and 44, getting-started/README.md line 20), but here and in common-problems.md line 92 it's called New Queue. Pick one and use it in all three places so users searching the UI for the exact label always find it. If the actual button label is "New Queue" today, the older pages need a follow-up update; if it's "Create New Queue", these new mentions should match.
| 1. Navigate to **Merge Queue** and click **New Queue** at the top right | |
| 1. Navigate to **Merge Queue** and click **Create New Queue** at the top right |
|
|
||
| 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. |
There was a problem hiding this comment.
Minor: repo is informal compared to the rest of this page (and section heading), which uses repository. Also, the qualifier is a bit redundant since the whole section is scoped to a single repository — consider trimming.
| 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. | |
| Each queue operates independently. PRs submitted to one queue don't interact with PRs in another queue, and every queue has its own settings, including merge method, required statuses, batching, and concurrency. |
| * **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. |
There was a problem hiding this comment.
Grammar nit: "In the Settings page" reads a bit awkwardly — the conventional preposition is "On the Settings page" (or just "In Settings"). Same suggestion lets you tighten the sentence too.
| 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. | |
| On 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. |
|
|
||
| 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`. |
There was a problem hiding this comment.
Style nit: "create a second queue against the same branch" — "against" reads a bit oddly here. "for the same branch" or "targeting the same branch" matches the language used in the section's first paragraph ("each queue targeting a different branch").
| 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`. | |
| A branch can only be associated with one queue. Attempting to create a second queue targeting the same branch returns the error `A merge queue already exists for branch "<branch>" in this repository`. |
|
|
||
| The Merge Queue dashboard groups queues by repository: | ||
|
|
||
| * **Single-queue repos**: The repository row is itself a link that goes directly to the queue. |
There was a problem hiding this comment.
Style nit: "is itself a link that goes directly to the queue" is a bit roundabout. Tightening it improves parallelism with the Multi-queue repos bullet below.
| * **Single-queue repos**: The repository row is itself a link that goes directly to the queue. | |
| * **Single-queue repos**: The repository row links directly to the queue. |
| 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. |
There was a problem hiding this comment.
Same button-label inconsistency I flagged in advanced-settings.md line 118 — the rest of the docs (e.g., install-and-create-your-queue.md) call this Create New Queue. Should match whichever label is correct in the live UI.
| 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. | |
| 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. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
1 participant
Summary
Context links
allowCreatingMultipleMergeQueuesFromWeb)useClickhouseForMergeDashboard, ships new accordion dashboard)Files changed
merge-queue/administration/advanced-settings.md— new sectionmerge-queue/reference/common-problems.md— updated FAQ answermerge-queue/getting-started/install-and-create-your-queue.md— added hintVerified facts
One-queue-per-branch is enforced. Each branch can only be associated with one queue. Validation lives at three layers in trunk2: a frontend
validateBranchcheck againstmergeInstanceBranches, a service-layerMERGE_INSTANCE_ALREADY_EXISTSerror, and a backend duplicate check. Phil Vendola confirmed in#trunk-appliedintuition2026-02-06: "still one queue per branch." Documented in both pages.No documented per-repo queue limit. No
MAX_QUEUESconstant or PRD reference. Production usage shows up to 13 queues per repo without friction (Trunk Support bot query,#team-go-to-market, 2026-04-30). Not documenting a limit since none exists in code.Screenshots / video for the new accordion dashboard. PR trunk-io/trunk2#2795 contains a demo video and a before image (GitHub user-attachment URLs, auth-gated to the private repo). PR trunk-io/trunk2#2901 has a follow-up UX polish video. Native screenshots for the docs site can be captured in a follow-up PR.
Test plan
🤖 Generated with Claude Code