diff --git a/docs/src/content/docs/patterns/label-ops.md b/docs/src/content/docs/patterns/label-ops.md index 5f2e38e252..e9529525b3 100644 --- a/docs/src/content/docs/patterns/label-ops.md +++ b/docs/src/content/docs/patterns/label-ops.md @@ -59,8 +59,16 @@ on: label_command: names: [deploy, redeploy] events: [pull_request] + +# Keep label after activation (persistent state, not one-shot command) +on: + label_command: + name: in-review + remove_label: false ``` +The `remove_label` field (boolean, default `true`) controls whether the matched label is removed after the workflow activates. Set it to `false` when the label represents a persistent state rather than a transient command — for example, to mark that an item is currently being processed without consuming the label. When `remove_label: false`, the `issues: write` / `pull-requests: write` permissions for label removal are not required. + The compiler generates `issues`, `pull_request`, and/or `discussion` events with `types: [labeled]`, filtered to the named labels. It also adds a `workflow_dispatch` trigger with an `item_number` input so you can test the workflow manually without applying a real label. ### Accessing the matched label diff --git a/docs/src/content/docs/reference/triggers.md b/docs/src/content/docs/reference/triggers.md index b00fb4d78b..f433b5ac94 100644 --- a/docs/src/content/docs/reference/triggers.md +++ b/docs/src/content/docs/reference/triggers.md @@ -297,12 +297,20 @@ on: name: deploy events: [pull_request] +# Disable automatic label removal (label stays on the item after activation) +on: + label_command: + name: deploy + remove_label: false + # Shorthand string form on: "label-command deploy" ``` The compiler generates `issues`, `pull_request`, and/or `discussion` events with `types: [labeled]`, adds a `workflow_dispatch` trigger with `item_number` for manual testing, and injects a label removal step in the activation job. The matched label name is exposed as `needs.activation.outputs.label_command`. +The `remove_label` field (boolean, default `true`) controls whether the label is automatically removed after activation. Set to `false` to keep the label on the item — useful when the label represents persistent state rather than a one-shot command. When `remove_label: false`, the workflow does not need `issues: write` or `pull-requests: write` permissions for label removal. + `label_command` can be combined with `slash_command:` — the workflow activates when either condition is met. See [LabelOps](/gh-aw/patterns/label-ops/) for patterns and examples. ### Label Filtering (`names:`)