From 58423c27bf93ba59578aedecbb6d453a9ca5bb3e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 3 Apr 2026 20:32:32 +0000 Subject: [PATCH] docs: update docs for 2026-04-03 merged features - Fix add-wizard incorrectly listed as supporting --create-pull-request in the GHES paragraph (closes #24312) - Document compile --json labels field and create_labels maintenance operation (from #24341) - Document logs --train flag and audit report Agent Event Pattern Analysis section (from #24328) - Document agent_usage.json token artifact in compilation-process reference (from #24315) Co-Authored-By: Claude Sonnet 4.6 --- docs/src/content/docs/guides/ephemerals.md | 13 ++++++++++++- .../docs/reference/compilation-process.md | 1 + docs/src/content/docs/setup/cli.md | 17 ++++++++++++++--- 3 files changed, 27 insertions(+), 4 deletions(-) diff --git a/docs/src/content/docs/guides/ephemerals.md b/docs/src/content/docs/guides/ephemerals.md index faa712098ca..dbdb00d7019 100644 --- a/docs/src/content/docs/guides/ephemerals.md +++ b/docs/src/content/docs/guides/ephemerals.md @@ -89,7 +89,18 @@ See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) for complete docume ### Manual Maintenance Operations -The generated `agentics-maintenance.yml` workflow also supports manual bulk operations via `workflow_dispatch`. Admin or maintainer users can trigger it from the GitHub Actions UI or the CLI to disable or enable all agentic workflows in the repository at once. The operation is restricted to admin and maintainer roles and is not available on forks. +The generated `agentics-maintenance.yml` workflow also supports manual bulk operations via `workflow_dispatch`. Admin or maintainer users can trigger it from the GitHub Actions UI or the CLI. The operation is restricted to admin and maintainer roles and is not available on forks. + +Available operations: + +| Operation | Description | +|-----------|-------------| +| `safe_outputs` | Auto-close expired issues, discussions, and pull requests | +| `disable` | Disable all agentic workflows in the repository | +| `enable` | Re-enable all agentic workflows in the repository | +| `create_labels` | Create any repository labels referenced in safe-outputs that do not yet exist. Runs `gh aw compile --json --no-emit`, collects all unique label names across workflows, and creates missing ones with deterministic pastel colors. | + +The `create_labels` operation requires `issues: write` permission and runs in a dedicated job. It is useful when adding new workflows that reference labels that have not yet been created in the repository. ### Close Older Issues diff --git a/docs/src/content/docs/reference/compilation-process.md b/docs/src/content/docs/reference/compilation-process.md index 82267edecd3..23962e23873 100644 --- a/docs/src/content/docs/reference/compilation-process.md +++ b/docs/src/content/docs/reference/compilation-process.md @@ -250,6 +250,7 @@ Workflows generate several artifacts during execution: | Artifact | Location | Purpose | Lifecycle | |----------|----------|---------|-----------| | **agent_output.json** | `/tmp/gh-aw/safeoutputs/` | AI agent output with structured safe output data (create_issue, add_comment, etc.) | Uploaded by agent job, downloaded by safe output jobs, auto-deleted after 90 days | +| **agent_usage.json** | `/tmp/gh-aw/` | Aggregated token counts: `{"input_tokens":…,"output_tokens":…,"cache_read_tokens":…,"cache_write_tokens":…}` | Bundled in the unified agent artifact when the firewall is enabled; accessible to third-party tools without parsing step summaries | | **prompt.txt** | `/tmp/gh-aw/aw-prompts/` | Generated prompt sent to AI agent (includes markdown instructions, imports, context variables) | Retained for debugging and reproduction | | **firewall-logs/** | `/tmp/gh-aw/firewall-logs/` | Network access logs in Squid format (when `network.firewall:` enabled) | Analyzed by `gh aw logs` command | | **cache-memory/** | `/tmp/gh-aw/cache-memory/` | Persistent agent memory across runs (when `tools.cache-memory:` configured) | Restored at start, saved at end via GitHub Actions cache | diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md index f03c66cd951..91d679ff62c 100644 --- a/docs/src/content/docs/setup/cli.md +++ b/docs/src/content/docs/setup/cli.md @@ -77,7 +77,7 @@ gh aw logs workflow --repo github.enterprise.com/owner/repo # Use with comm For GHE Cloud with data residency (`*.ghe.com`), see the dedicated [Debugging GHE Cloud guide](/gh-aw/troubleshooting/debug-ghe/) for setup and troubleshooting steps. -Commands that support `--create-pull-request` (such as `gh aw add`, `gh aw add-wizard`, `gh aw init`, `gh aw update`, and `gh aw upgrade`) automatically detect the enterprise host from the git remote and route PR creation to the correct GHES instance. No extra flags are needed. +Commands that support `--create-pull-request` (such as `gh aw add`, `gh aw init`, `gh aw update`, and `gh aw upgrade`) automatically detect the enterprise host from the git remote and route PR creation to the correct GHES instance. No extra flags are needed. `gh aw audit` and `gh aw add-wizard` also auto-detect the GHES host from the git remote, so running them inside a GHES repository works without setting `GH_HOST` manually. @@ -254,10 +254,12 @@ gh aw compile --dependabot # Generate dependency manifests gh aw compile --purge # Remove orphaned .lock.yml files ``` -**Options:** `--validate`, `--strict`, `--fix`, `--zizmor`, `--dependabot`, `--json`, `--watch`, `--purge`, `--stats` +**Options:** `--validate`, `--strict`, `--fix`, `--zizmor`, `--dependabot`, `--json`, `--no-emit`, `--watch`, `--purge`, `--stats` **Error Reporting:** Displays detailed error messages with file paths, line numbers, column positions, and contextual code snippets. +**JSON Output (`--json`):** Emits an array of `ValidationResult` objects. Each result includes a `labels` field listing all repository labels referenced in safe-outputs (`create-issue.labels`, `create-discussion.labels`, `create-pull-request.labels`, `add-labels.allowed`). Use `--json --no-emit` to collect label references without writing compiled files. + **Dependabot Integration (`--dependabot`):** Generates dependency manifests and `.github/dependabot.yml` by analyzing runtime tools across all workflows. See [Dependabot Support reference](/gh-aw/reference/dependabot/). **Strict Mode (`--strict`):** Enforces security best practices: no write permissions (use [safe-outputs](/gh-aw/reference/safe-outputs/)), explicit `network` config, no wildcard domains, pinned Actions, no deprecated fields. See [Strict Mode reference](/gh-aw/reference/frontmatter/#strict-mode-strict). @@ -380,7 +382,14 @@ gh aw logs "CI Failure Doctor" # Display name gh aw logs "ci failure doctor" # Case-insensitive display name ``` -**Options:** `-c`, `--count`, `-e`, `--engine`, `--start-date`, `--end-date`, `--ref`, `--parse`, `--json`, `--repo`, `--firewall`, `--no-firewall`, `--safe-output`, `--filtered-integrity`, `--after-run-id`, `--before-run-id`, `--no-staged`, `--tool-graph`, `--timeout` +**`--train` flag:** Trains log template weights from the downloaded runs and writes `drain3_weights.json` to the logs output directory. The trained weights improve anomaly detection accuracy in subsequent `gh aw audit` and `gh aw logs` runs. To embed weights into the binary as defaults, copy the file to `pkg/agentdrain/data/default_weights.json` and rebuild. + +```bash wrap +gh aw logs --train # Train on last 10 runs +gh aw logs my-workflow --train -c 50 # Train on up to 50 runs of a specific workflow +``` + +**Options:** `-c`, `--count`, `-e`, `--engine`, `--start-date`, `--end-date`, `--ref`, `--parse`, `--json`, `--train`, `--repo`, `--firewall`, `--no-firewall`, `--safe-output`, `--filtered-integrity`, `--after-run-id`, `--before-run-id`, `--no-staged`, `--tool-graph`, `--timeout` #### `audit` @@ -450,6 +459,8 @@ gh aw audit report --repo owner/repo --last 10 # Report on a specif Output is Markdown by default (suitable for security reviews, piping to files, or `$GITHUB_STEP_SUMMARY`). +The report includes an **Agent Event Pattern Analysis** section that mines log templates across runs using an online clustering algorithm. It surfaces distinct event patterns, stage sequences, and anomalies (new templates, low-similarity events, rare clusters) with severity indicators. + **Options:** `--workflow/-w` (filter by workflow name or filename), `--last` (number of recent runs to analyze; default: 20, max: 50), `--format` (markdown, pretty; default: markdown), `--json`, `--repo/-r` #### `health`