diff --git a/merge-queue/using-the-queue/reference.md b/merge-queue/using-the-queue/reference.md index 54d9d7bc..3faddf5c 100644 --- a/merge-queue/using-the-queue/reference.md +++ b/merge-queue/using-the-queue/reference.md @@ -20,6 +20,8 @@ trunk login trunk merge ``` +* 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. @@ -36,6 +38,8 @@ trunk login trunk merge cancel ``` +* Removing the configured enqueueing label from a pull request (when label commands are enabled). + ## 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: @@ -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 + +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 | + +The label must already exist in your GitHub repository. Trunk does not create the label automatically. + +{% 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.