From 59431e1265586a45298ad44624193cf18534efd3 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 25 Mar 2026 20:34:35 +0000 Subject: [PATCH] docs: document audit sections, toolsets: [all] behavior, and glob validation - cli.md: expand gh aw audit description with the new report sections added in #22932 (engine config, prompt analysis, session & agent performance, MCP server health, safe output summary) - github-tools.md: document toolsets shorthand values (default, all) and add a note that toolsets: [all] excludes dependabot (#22851) - triggers.md: document compile-time glob pattern validation for push/ pull_request/pull_request_target/workflow_run filter fields (#22873) Co-Authored-By: Claude Sonnet 4.6 --- .../content/docs/reference/github-tools.md | 19 ++++++++++++++++++- docs/src/content/docs/reference/triggers.md | 18 ++++++++++++++++++ docs/src/content/docs/setup/cli.md | 18 +++++++++++++++++- 3 files changed, 53 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/reference/github-tools.md b/docs/src/content/docs/reference/github-tools.md index 6ed3260b62..cb8816e6ea 100644 --- a/docs/src/content/docs/reference/github-tools.md +++ b/docs/src/content/docs/reference/github-tools.md @@ -21,6 +21,11 @@ tools: **Available**: `context`, `repos`, `issues`, `pull_requests`, `users`, `actions`, `code_security`, `discussions`, `labels`, `notifications`, `orgs`, `projects`, `gists`, `search`, `dependabot`, `experiments`, `secret_protection`, `security_advisories`, `stargazers` +**Shorthand values**: + +- `default` — expands to `context`, `repos`, `issues`, `pull_requests`, `users` +- `all` — expands to all available toolsets **except** `dependabot` (see note below) + **Default**: `context`, `repos`, `issues`, `pull_requests`, `users` Some key toolsets are: @@ -34,7 +39,19 @@ Some key toolsets are: - `discussions` (discussions and comments) - `labels` (labels management) -Some toolsets requuire [additional authentication](#additional-authentication-for-github-tools). +:::note +`toolsets: [all]` does **not** include the `dependabot` toolset. Because `dependabot` requires the `vulnerability-alerts` GitHub App-only permission (not grantable via `GITHUB_TOKEN`), it must be opted into explicitly: + +```yaml wrap +tools: + github: + toolsets: [all, dependabot] +``` + +See [Using the `dependabot` toolset](#using-the-dependabot-toolset) for authentication requirements. +::: + +Some toolsets require [additional authentication](#additional-authentication-for-github-tools). ## GitHub Integrity Filtering (`tools.github.min-integrity`) diff --git a/docs/src/content/docs/reference/triggers.md b/docs/src/content/docs/reference/triggers.md index 57b8152694..774830cc62 100644 --- a/docs/src/content/docs/reference/triggers.md +++ b/docs/src/content/docs/reference/triggers.md @@ -604,6 +604,24 @@ on: pull_request opened affecting docs/** # Activity type + path filter `pull` is an alias for `pull_request`. Valid activity types: `opened`, `edited`, `closed`, `reopened`, `synchronize`, `assigned`, `unassigned`, `labeled`, `unlabeled`, `review_requested`, `merged`. +#### Glob Pattern Validation + +The compiler validates glob patterns in `branches`, `branches-ignore`, `tags`, `tags-ignore`, and `paths`/`paths-ignore` filter fields at compile time for `push`, `pull_request`, `pull_request_target`, and `workflow_run` triggers. Invalid patterns produce a compilation error: + +```yaml wrap +on: + push: + paths: + - ./src/**/*.go # error: invalid glob pattern "./src/**/*.go" in on.push.paths + branches: + - main branch # error: invalid glob pattern "main branch" in on.push.branches +``` + +Common invalid patterns: +- **`./`-prefixed paths** — use `src/**` not `./src/**` +- **Spaces in ref patterns** — branch/tag names cannot contain spaces +- **Unclosed brackets** — e.g. `feat[` without a closing `]` + ### Issues and Discussions ```yaml wrap diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md index 27aabcd359..2c90089846 100644 --- a/docs/src/content/docs/setup/cli.md +++ b/docs/src/content/docs/setup/cli.md @@ -381,7 +381,7 @@ gh aw logs "ci failure doctor" # Case-insensitive display name #### `audit` -Analyze specific runs with overview, metrics, tool usage, MCP failures, firewall analysis, noops, and artifacts. Accepts run IDs, workflow run URLs, job URLs, and step-level URLs. Auto-detects Copilot coding agent runs for specialized parsing. Job URLs automatically extract specific job logs; step URLs extract specific steps; without step, extracts first failing step. +Analyze specific runs with a rich multi-section report. Accepts run IDs, workflow run URLs, job URLs, and step-level URLs. Auto-detects Copilot coding agent runs for specialized parsing. Job URLs automatically extract specific job logs; step URLs extract specific steps; without step, extracts first failing step. ```bash wrap gh aw audit 12345678 # By run ID @@ -398,6 +398,22 @@ The `--repo` flag accepts `owner/repo` format and is required when passing a bar Logs are saved to `logs/run-{id}/` with filenames indicating the extraction level. Pre-agent failures (integrity filtering, missing secrets, binary install) surface the actual error in `failure_analysis.error_summary`. Invalid run IDs return a human-readable error. +**Report sections:** + +| Section | Description | +|---------|-------------| +| **Overview** | Run status, duration, trigger event, repository | +| **Engine Configuration** | Engine ID, model, CLI version, firewall version, MCP servers configured | +| **Prompt Analysis** | Prompt size and source file | +| **Session & Agent Performance** | Wall time, turn count, average turn duration, tokens per minute, timeout detection, agent active ratio | +| **MCP Server Health** | Per-server request counts, error rates, average latency, health status, and slowest tool calls | +| **Safe Output Summary** | Total safe output items broken down by type (comments, PRs, issues, etc.) | +| **Metrics** | Tool usage, token consumption, cost | +| **MCP Failures** | Failed MCP tool calls with error details | +| **Firewall Analysis** | Network requests blocked or allowed by the firewall | +| **Jobs** | Status of each GitHub Actions job in the run | +| **Artifacts** | Downloaded artifacts and their contents | + #### `health` Display workflow health metrics and success rates.