Skip to content

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

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 #661

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,31 @@ 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.

Missing cross-reference for parallelism with line 23. The submission bullet (line 23) helpfully links to the Label Commands section, but the matching cancellation bullet here doesn't. A reader who lands on the cancellation list first won't know where to learn more. Suggest mirroring the submission bullet:

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).


## 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 +43 to +47
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 case inconsistent with rest of file. Every other ## and ### heading in reference.md uses sentence case (## Submitting and cancelling pull requests, ## Custom merge commit titles, ### How it works, ### Example), but the new headings use Title Case. Consider matching the file's existing convention:

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

If you do this, also lowercase "Label Commands" in prose on lines 49 and 51 (and the link text on line 23) so the term is treated consistently as a feature description rather than a proper noun.

Fix this →


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`.
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.

Vague on where to configure the label name. "You can configure the enqueueing label name" implies a setting somewhere, but doesn't say where. Is it the same Merge Queue Settings > Label Commands location mentioned in the previous sentence, or somewhere else? Consider making it explicit, e.g.:

When enabled, you can set a custom label name in the same panel. The default is trunk-merge-queue-submit.

Also worth confirming whether changing the label name applies retroactively (do PRs already carrying the old label get cancelled? does it require a label to exist beforehand, per line 60?). If there's a known answer, surfacing it here would save a support ticket.


### 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 |

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.

Consider promoting to a warning callout for visibility. This is a precondition that, if missed, will silently break the feature — users may assume Trunk creates the label and wonder why nothing happens when they apply it. The next paragraph is already a {% hint style="info" %}, so the contrast in style suggests this line is less important than it actually is. Suggest:

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


{% 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 %}

## 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
Loading