Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
8 changes: 8 additions & 0 deletions docs/src/content/docs/patterns/label-ops.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link

Copilot AI Mar 19, 2026

Choose a reason for hiding this comment

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

This sentence references pull-requests: write as the relevant permission for label removal. In the current implementation, label removal for pull requests uses the Issues REST API (so it’s issues: write), and discussion label removal uses discussions: write; pull-requests: write is not required for label removal. Recommend updating this line (and the later NOTE in this doc about permissions for automatic label removal) to reflect the actual permissions avoided when remove_label: false.

Suggested change
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 `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` (for issues and pull requests) and `discussions: write` permissions used for label removal are not required.

Copilot uses AI. Check for mistakes.

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
Expand Down
8 changes: 8 additions & 0 deletions docs/src/content/docs/reference/triggers.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment on lines 310 to +312
Copy link

Copilot AI Mar 19, 2026

Choose a reason for hiding this comment

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

The surrounding description implies the activation job always injects a label-removal step and that label removal is associated with pull-requests: write. In the implementation, label removal is conditional (remove_label: false swaps the removal step for get_trigger_label.cjs), and PR label removal uses the Issues API (so it’s governed by issues: write), while discussions use discussions: write. Suggest updating this paragraph to reflect the conditional step and to reference the correct permissions (issues: write for issues/pull_request; discussions: write for discussion) that are avoided when remove_label: false.

Suggested change
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.
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, when `remove_label` is `true` (the default), 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 perform label removal, so it does not require additional write permissions for label changes (avoiding `issues: write` for issues/pull_request items and `discussions: write` for discussions).

Copilot uses AI. Check for mistakes.

`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:`)
Expand Down
Loading