Skip to content

[feature not live] docs(merge-queue): document configurable label commands for enqueueing #659

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
samgutentag wants to merge 1 commit into
base: main
Choose a base branch
from
+27 −0
Draft

[feature not live] docs(merge-queue): document configurable label commands for enqueueing #659

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions merge-queue/using-the-queue/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ trunk login
trunk merge <pr-number>
```

* Applying the configured enqueueing label to a pull request (when label commands are enabled — see [Label Commands](#label-commands) below).

Admins can also use [`/trunk merge --force`](force-merge.md) to push a PR through the queue when branch protection isn't satisfied.

We offer similar commands for cancellation.
Expand All @@ -36,6 +38,8 @@ trunk login
trunk merge cancel <pr-number>
```

* Removing the configured enqueueing label from a pull request (when label commands are enabled).
Copy link
Copy Markdown
Contributor

@claude claude Bot May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor consistency: the parallel bullet on line 23 links readers to the [Label Commands](#label-commands) section, but this bullet only says "(when label commands are enabled)" without the same anchor link. For users skimming the cancellation list, the link is just as useful. Consider mirroring line 23:

Suggested change
* Removing the configured enqueueing label from a pull request (when label commands are enabled).
* Removing the configured enqueueing label from a pull request (when label commands are enabled — see [Label Commands](#label-commands) below).


## Custom merge commit titles

You can specify a custom merge commit title for any PR by adding a `merge-commit-title:` directive on its own line anywhere in the PR body:
Expand Down Expand Up @@ -65,6 +69,29 @@ The `merge-commit-title:` directive only customizes the merge commit **title**.
The directive applies to the **Squash** and **Merge Commit** merge methods. It has no effect when using **Rebase**, since rebase replays the original commits onto the target branch and does not produce a separate merge commit.
{% endhint %}

## Label Commands

Label Commands let you enqueue and cancel PRs in the Merge Queue by applying or removing a GitHub label, without leaving a comment or using the CLI.

### Enabling Label Commands
Comment on lines +72 to +76
Copy link
Copy Markdown
Contributor

@claude claude Bot May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Heading capitalization is inconsistent with the rest of the page.

Every other ##/### heading on this page uses sentence case (e.g. ## Submitting and cancelling pull requests, ## Custom merge commit titles, ## Pull request processing, ## Pull request states, ### Example). The new section uses Title Case for ## Label Commands and ### Enabling Label Commands, but then drops back to sentence case for ### How it works — so it's also internally inconsistent.

Recommend sentence case throughout to match the rest of the page:

Suggested change
## Label Commands
Label Commands let you enqueue and cancel PRs in the Merge Queue by applying or removing a GitHub label, without leaving a comment or using the CLI.
### Enabling Label Commands
## Label commands
Label Commands let you enqueue and cancel PRs in the Merge Queue by applying or removing a GitHub label, without leaving a comment or using the CLI.
### Enabling label commands

(You can keep "Label Commands" capitalized in body prose where it refers to the setting name in the UI — the recommendation is just about heading style.)


Label Commands are configured per merge queue instance in **Merge Queue Settings** > **Label Commands**. Only organization admins can change this setting.

When Label Commands are enabled, you can configure the enqueueing label name. The default label is `trunk-merge-queue-submit`.

### How it works

| Action | Effect |
| ------ | ------ |
| Apply the enqueueing label to a PR | Submits the PR to the Merge Queue |
| Remove the enqueueing label from a PR | Cancels the PR from the queue |
Comment on lines +86 to +87
Copy link
Copy Markdown
Contributor

@claude claude Bot May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inconsistent terminology within adjacent rows: the "Submit" row says "Merge Queue" (capitalized) and the "Cancel" row says "queue" (lowercase, no "Merge"). Pick one for both rows.

Suggested change
| Apply the enqueueing label to a PR | Submits the PR to the Merge Queue |
| Remove the enqueueing label from a PR | Cancels the PR from the queue |
| Apply the enqueueing label to a PR | Submits the PR to the Merge Queue |
| Remove the enqueueing label from a PR | Cancels the PR from the Merge Queue |


The label must already exist in your GitHub repository. Trunk does not create the label automatically.
Copy link
Copy Markdown
Contributor

@claude claude Bot May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: This is an important "gotcha" — if the label doesn't exist, nothing happens. It would stand out more (and match the pattern used for the existing info hint below) if wrapped in a warning hint:

{% hint style="warning" %}
The label must already exist in your GitHub repository. Trunk does not create the label automatically.
{% endhint %}

Non-blocking — leaving as a plain paragraph is also fine.


{% hint style="info" %}
Label Commands work alongside comment commands and the Trunk web app. You can use any combination of submission methods; they all target the same queue.
{% endhint %}

## Pull request processing

Once a PR is submitted to the merge queue it goes through several states. First, it starts as _Queued_ until all of the required conditions to submit it are met. Once ready, the PR moves to the _Pending_ state, waiting for a Merge Queue to pick it up, and then enters the _Testing_ state. Once the tests pass the PR may still need to wait for upstream PRs. Once any upstream PRs are complete the PR will be merged and then removed from the Merge Queue. If a PR fails or is canceled then it will go to the failed or canceled state.
Expand Down
Loading