Skip to content

docs(merge-queue): add State Labels setting #235

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

Open
samgutentag wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(merge-queue): add State Labels setting #235

Show file tree
Hide file tree
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
16 changes: 16 additions & 0 deletions changelog/2026-06-10-merge-queue-state-labels-setting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
---
title: "Merge Queue: Enable or Disable PR State Labels"
description: "A new toggle in Merge Queue Settings lets you enable or disable GitHub labels that Trunk applies to pull requests to reflect their current queue state."
date: 2026-06-10
category: Merge Queue
type: update
---

**Merge Queue can now apply GitHub labels to pull requests showing their current queue state.**

A new **State Labels** toggle in Merge Queue Settings controls whether Trunk applies labels to pull requests as they move through the queue. When enabled, PRs receive labels such as `trunk:queued`, `trunk:testing`, and `trunk:failed` that are visible directly in GitHub's pull request list without opening the Trunk dashboard.

- **Disabled by default.** Enable the toggle in **Merge Queue** -> **[your repository]** -> **Settings** -> **State Labels**.
- **Admin-only.** Only organization admins can change this setting.

See [State Labels](https://docs.trunk.io/merge-queue/administration/advanced-settings#state-labels) in the settings reference for details.
1 change: 1 addition & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -618,6 +618,7 @@
{
"group": "June",
"pages": [
"changelog/2026-06-10-merge-queue-state-labels-setting",
"changelog/2026-06-08-merge-queue-firefox-extension",
"changelog/2026-06-04-merge-queue-chrome-extension-0-8-0"
]
Expand Down
31 changes: 31 additions & 0 deletions merge-queue/administration/advanced-settings.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -282,6 +282,37 @@ When enabled, Trunk posts comments on pull requests with merge queue status upda

***

## State Labels

> Toggle this feature **Enabled** or **Disabled**. Default is **Disabled**.

When enabled, Trunk applies GitHub labels to pull requests to reflect their current position in the merge queue. Labels update automatically as a PR moves through states, making queue activity visible directly in GitHub's pull request list without opening the Trunk dashboard.

**Labels applied:**

| Queue state | Label |
|---|---|
| Queued | `trunk:queued` |
| Testing | `trunk:testing` |
| Tests Passed | `trunk:tests-passed` |
| Pending Failure | `trunk:pending-failure` |
| Failed | `trunk:failed` |
| Merged | `trunk:merged` |
| Cancelled | `trunk:cancelled` |

Trunk adds the label when a PR enters a state and removes it when the state changes. Only one state label is on a PR at a time.

**When to enable:**

* **GitHub-first workflows** - Your team tracks PR status directly in GitHub rather than the Trunk dashboard.
* **Automations based on merge state** - Other tools or GitHub Actions can trigger on label changes to react to queue events.

<Info>
Only organization admins can change this setting.
</Info>

***

## GitHub Statuses

> Toggle this feature **Enabled** or **Disabled**. Default is **Enabled**.
Expand Down
Loading