From 7e47579b18e00321dff831ebd8ca98b58ad56eab Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 12 Apr 2026 10:00:15 +0000 Subject: [PATCH 1/3] Initial plan From 7f7b522dbbec37b7f0814a5448ac82ec730a2b39 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 12 Apr 2026 10:13:57 +0000 Subject: [PATCH 2/3] docs: update slash command documentation with event filtering details Expand the "Filtering Command Events" section in command-triggers.md with: - Motivation explaining the noise problem from default all-events triggers - Structured table of all supported event identifiers - Issue-only example workflow for bug investigation pipelines - PR-only example workflow - Note about pull_request_comment vs issue_comment mapping Also expand the slash_command section in triggers.md with an inline event filtering example. Agent-Logs-Url: https://github.com/github/gh-aw/sessions/f6fde4fd-e1f4-46de-a141-0553f9fdd303 Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .../docs/reference/command-triggers.md | 67 ++++++++++++++++--- docs/src/content/docs/reference/triggers.md | 13 +++- 2 files changed, 69 insertions(+), 11 deletions(-) diff --git a/docs/src/content/docs/reference/command-triggers.md b/docs/src/content/docs/reference/command-triggers.md index ed5c20bd4c0..2f408052473 100644 --- a/docs/src/content/docs/reference/command-triggers.md +++ b/docs/src/content/docs/reference/command-triggers.md @@ -83,7 +83,9 @@ This pattern is useful when you want a workflow that can be triggered both manua ## Filtering Command Events -By default, command triggers respond to `/command-name` mentions in all comment-related contexts. Use the `events:` field to restrict where commands are active: +By default, command triggers respond to `/command-name` mentions in **all** comment-related contexts: issue bodies, issue comments, PR bodies, PR comments, PR review comments, discussion bodies, and discussion comments. This means every PR open/edit event triggers the workflow even if it gets skipped at the activation gate — showing up as skipped runs in the Actions UI. + +Use the `events:` field to restrict where commands are active and eliminate unnecessary workflow runs: ```yaml wrap on: @@ -92,31 +94,54 @@ on: events: [issues, issue_comment] # Only in issue bodies and issue comments ``` -**Supported events:** `issues` (issue bodies), `issue_comment` (issue comments only), `pull_request_comment` (PR comments only), `pull_request` (PR bodies), `pull_request_review_comment` (PR review comments), `discussion` (discussion bodies), `discussion_comment` (discussion comments), or `*` (all comment events, default). +### Supported event identifiers + +| Event identifier | Description | +|---|---| +| `issues` | Issue bodies (opened, edited, reopened) | +| `issue_comment` | Comments on issues only (excludes PR comments) | +| `pull_request` | Pull request bodies (opened, edited, reopened) | +| `pull_request_comment` | Comments on pull requests only (excludes issue comments) | +| `pull_request_review_comment` | Pull request review comments | +| `discussion` | Discussion bodies | +| `discussion_comment` | Discussion comments | +| `*` | All comment-related events (default when `events:` is omitted) | + +:::note +Both `issue_comment` and `pull_request_comment` map to GitHub Actions' `issue_comment` event but with automatic filtering to distinguish between issue comments and PR comments. This provides precise control over where your commands are active. +::: -### Example command workflow +### Issue-only commands -Using object format: +For workflows where the slash command only makes sense on issues (e.g., bug investigation pipelines), restrict events to `issues` and `issue_comment` to avoid generating skipped runs from pull request activity: ```aw wrap --- on: slash_command: - name: summarize-issue + name: investigate + events: [issues, issue_comment] # Skip PR events entirely +permissions: + contents: read + issues: write tools: github: toolsets: [issues] --- -# Issue Summarizer +# Bug Investigator -When someone mentions /summarize-issue in an issue or comment, -analyze and provide a helpful summary. +When someone mentions /investigate in an issue or issue comment, +analyze the reported bug and provide an investigation summary. -The current context text is: "${{ steps.sanitized.outputs.text }}" +The current context is: "${{ steps.sanitized.outputs.text }}" ``` -PR-focused example using event filtering to restrict to pull requests and PR comments: +Without the `events` filter, this workflow would trigger on every PR open and edit event, immediately get skipped at the pre-activation gate, and show up as a cancelled run in the Actions tab. + +### PR-only commands + +For commands that only apply to pull requests and PR comments: ```aw wrap --- @@ -146,6 +171,28 @@ Review the pull request changes and add helpful review comments on specific lines of code where improvements can be made. ``` +### General command workflow + +Using object format without event filtering (responds to all comment-related events): + +```aw wrap +--- +on: + slash_command: + name: summarize-issue +tools: + github: + toolsets: [issues] +--- + +# Issue Summarizer + +When someone mentions /summarize-issue in an issue or comment, +analyze and provide a helpful summary. + +The current context text is: "${{ steps.sanitized.outputs.text }}" +``` + ## Context Text All workflows access `steps.sanitized.outputs.text`, which provides **sanitized** context: for issues and PRs, it's `title + "\n\n" + body`; for comments and reviews, it's the body content. diff --git a/docs/src/content/docs/reference/triggers.md b/docs/src/content/docs/reference/triggers.md index 55e7d05bf16..e4168da2087 100644 --- a/docs/src/content/docs/reference/triggers.md +++ b/docs/src/content/docs/reference/triggers.md @@ -281,7 +281,18 @@ See the [Security Architecture](/gh-aw/introduction/architecture/) for details. ### Command Triggers (`slash_command:`) -The `slash_command:` trigger creates workflows that respond to `/command-name` mentions in issues, pull requests, and comments. See [Command Triggers](/gh-aw/reference/command-triggers/) for complete documentation including event filtering, context text, reactions, and examples. +The `slash_command:` trigger creates workflows that respond to `/command-name` mentions in issues, pull requests, and comments. + +By default, command triggers listen to **all** comment-related events, which can create noise from skipped runs. Use the `events:` field to restrict where commands are active: + +```yaml wrap +on: + slash_command: + name: investigate + events: [issues, issue_comment] # Only respond in issue contexts +``` + +See [Command Triggers](/gh-aw/reference/command-triggers/) for complete documentation including event filtering, context text, reactions, and examples. ### Label Command Trigger (`label_command:`) From b294b2ef206ca9d1736af29726c81c21320e0daf Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 12 Apr 2026 10:36:43 +0000 Subject: [PATCH 3/3] docs: trim bloated examples and remove write permission recommendations Agent-Logs-Url: https://github.com/github/gh-aw/sessions/521794fa-c4ca-4e3c-9992-a31336bfbb56 Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .../docs/reference/command-triggers.md | 93 ++----------------- 1 file changed, 9 insertions(+), 84 deletions(-) diff --git a/docs/src/content/docs/reference/command-triggers.md b/docs/src/content/docs/reference/command-triggers.md index 2f408052473..97163e93447 100644 --- a/docs/src/content/docs/reference/command-triggers.md +++ b/docs/src/content/docs/reference/command-triggers.md @@ -83,9 +83,7 @@ This pattern is useful when you want a workflow that can be triggered both manua ## Filtering Command Events -By default, command triggers respond to `/command-name` mentions in **all** comment-related contexts: issue bodies, issue comments, PR bodies, PR comments, PR review comments, discussion bodies, and discussion comments. This means every PR open/edit event triggers the workflow even if it gets skipped at the activation gate — showing up as skipped runs in the Actions UI. - -Use the `events:` field to restrict where commands are active and eliminate unnecessary workflow runs: +By default, command triggers listen to all comment-related events, which can create skipped runs in the Actions UI. Use the `events:` field to restrict where commands are active: ```yaml wrap on: @@ -94,103 +92,30 @@ on: events: [issues, issue_comment] # Only in issue bodies and issue comments ``` -### Supported event identifiers - -| Event identifier | Description | -|---|---| -| `issues` | Issue bodies (opened, edited, reopened) | -| `issue_comment` | Comments on issues only (excludes PR comments) | -| `pull_request` | Pull request bodies (opened, edited, reopened) | -| `pull_request_comment` | Comments on pull requests only (excludes issue comments) | -| `pull_request_review_comment` | Pull request review comments | -| `discussion` | Discussion bodies | -| `discussion_comment` | Discussion comments | -| `*` | All comment-related events (default when `events:` is omitted) | +**Supported events:** `issues`, `issue_comment`, `pull_request`, `pull_request_comment`, `pull_request_review_comment`, `discussion`, `discussion_comment`, or `*` (all, default). :::note -Both `issue_comment` and `pull_request_comment` map to GitHub Actions' `issue_comment` event but with automatic filtering to distinguish between issue comments and PR comments. This provides precise control over where your commands are active. +Both `issue_comment` and `pull_request_comment` map to GitHub Actions' `issue_comment` event with automatic filtering to distinguish between issue and PR comments. ::: -### Issue-only commands +### Example command workflow -For workflows where the slash command only makes sense on issues (e.g., bug investigation pipelines), restrict events to `issues` and `issue_comment` to avoid generating skipped runs from pull request activity: +Issue-only command (avoids skipped runs from PR events): -```aw wrap ---- +```yaml wrap on: slash_command: name: investigate - events: [issues, issue_comment] # Skip PR events entirely -permissions: - contents: read - issues: write -tools: - github: - toolsets: [issues] ---- - -# Bug Investigator - -When someone mentions /investigate in an issue or issue comment, -analyze the reported bug and provide an investigation summary. - -The current context is: "${{ steps.sanitized.outputs.text }}" + events: [issues, issue_comment] ``` -Without the `events` filter, this workflow would trigger on every PR open and edit event, immediately get skipped at the pre-activation gate, and show up as a cancelled run in the Actions tab. - -### PR-only commands +PR-only command: -For commands that only apply to pull requests and PR comments: - -```aw wrap ---- +```yaml wrap on: slash_command: name: code-review events: [pull_request, pull_request_comment] -permissions: - contents: read -tools: - github: - toolsets: [pull_requests] -safe-outputs: - add-comment: - max: 5 -timeout-minutes: 10 ---- - -# Code Review Assistant - -When someone mentions /code-review in a pull request or PR comment, -analyze the code changes and provide detailed feedback. - -The current context is: "${{ steps.sanitized.outputs.text }}" - -Review the pull request changes and add helpful review comments on specific -lines of code where improvements can be made. -``` - -### General command workflow - -Using object format without event filtering (responds to all comment-related events): - -```aw wrap ---- -on: - slash_command: - name: summarize-issue -tools: - github: - toolsets: [issues] ---- - -# Issue Summarizer - -When someone mentions /summarize-issue in an issue or comment, -analyze and provide a helpful summary. - -The current context text is: "${{ steps.sanitized.outputs.text }}" ``` ## Context Text