From 5520109b50c8bf1b9c9d3c90eca73352eaefc02f Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 21 Nov 2025 06:10:01 +0000 Subject: [PATCH] Update documentation for features from 2025-11-21 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated documentation based on merged pull requests from the last 24 hours. Features documented: - --progress flag for run command (PR #4450) - Noop message parsing in logs/audit commands (PR #4428) - close-discussion safe output type (PR #4411) - debug-agentic-workflow custom agent (PR #4449) - Audit command suggestion in run output (PR #4445) Changes: - Updated docs/setup/cli.md to document --progress flag and noop parsing - Updated docs/reference/safe-outputs.md to add close-discussion safe output - Updated docs/reference/custom-agents.md to mention debug-agentic-workflow 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../content/docs/reference/custom-agents.md | 4 +++ .../content/docs/reference/safe-outputs.md | 29 +++++++++++++++++++ docs/src/content/docs/setup/cli.md | 8 +++-- 3 files changed, 39 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/reference/custom-agents.md b/docs/src/content/docs/reference/custom-agents.md index d7158a1ba27..280e8676c65 100644 --- a/docs/src/content/docs/reference/custom-agents.md +++ b/docs/src/content/docs/reference/custom-agents.md @@ -48,3 +48,7 @@ The agent instructions are merged with the workflow prompt, customizing the AI e - **Format**: Markdown with YAML frontmatter - **Frontmatter**: Can include `name`, `description`, `tools`, and `mcp-servers` - **One per workflow**: Only one agent file can be imported per workflow + +## Built-in Custom Agents + +The `gh aw init` command sets up a `debug-agentic-workflow` custom agent that helps debug and refine workflows using CLI tools (`gh aw logs`, `gh aw audit`, `gh aw run`, `gh aw compile`). The agent provides conversational workflow debugging and performance analysis. diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md index 6ac3262b581..2c94b6d6400 100644 --- a/docs/src/content/docs/reference/safe-outputs.md +++ b/docs/src/content/docs/reference/safe-outputs.md @@ -34,6 +34,7 @@ This declares that the workflow should create at most one new issue. | **Create PR** | `create-pull-request:` | Create pull requests with code changes | 1 | ✅ | | **PR Review Comments** | `create-pull-request-review-comment:` | Create review comments on code lines | 1 | ✅ | | **Create Discussion** | `create-discussion:` | Create GitHub discussions | 1 | ✅ | +| **Close Discussion** | `close-discussion:` | Close discussions with comment and resolution | 1 | ✅ | | **Create Agent Task** | `create-agent-task:` | Create Copilot agent tasks | 1 | ✅ | | **Push to PR Branch** | `push-to-pull-request-branch:` | Push changes to PR branch | 1 | ❌ | | **Update Release** | `update-release:` | Update GitHub release descriptions | 1 | ✅ | @@ -286,6 +287,34 @@ safe-outputs: target-repo: "owner/repo" # Optional: cross-repository ``` +### Close Discussion (`close-discussion:`) + +Closes GitHub discussions with an optional comment and resolution reason. Supports filtering by category, labels, and title prefix to control which discussions can be closed. + +```yaml wrap +safe-outputs: + close-discussion: + target: "triggering" # Optional: "triggering" (default), "*", or number + required-category: "Ideas" # Optional: only close discussions in category + required-labels: [resolved] # Optional: only close with specific labels + required-title-prefix: "[ai]" # Optional: only close matching prefix + max: 1 # Optional: max closures (default: 1) + target-repo: "owner/repo" # Optional: cross-repository +``` + +**Target Resolution:** +- `"triggering"` (default): Requires discussion event trigger, resolves from context +- `"*"`: Allows closing any discussion, agent provides `discussion_number` +- Number: Closes specific discussion by number + +**Resolution Reasons:** +- `RESOLVED` - Discussion has been answered or resolved +- `DUPLICATE` - Discussion is a duplicate +- `OUTDATED` - Discussion is no longer relevant +- `ANSWERED` - Question has been answered + +All filters (`required-category`, `required-labels`, `required-title-prefix`) are optional safeguards applied during validation. + ### Agent Task Creation (`create-agent-task:`) Creates GitHub Copilot agent tasks to delegate coding tasks. Requires a PAT stored as `COPILOT_GITHUB_TOKEN` (recommended) or legacy `GH_AW_COPILOT_TOKEN` / `GH_AW_GITHUB_TOKEN`. diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md index 11a007e4559..f50d91624e6 100644 --- a/docs/src/content/docs/setup/cli.md +++ b/docs/src/content/docs/setup/cli.md @@ -228,11 +228,15 @@ gh aw run WorkflowName # Run workflow gh aw run workflow1 workflow2 # Run multiple workflows gh aw run workflow --repeat 3 # Repeat execution 3 times gh aw run workflow --use-local-secrets # Use local API keys +gh aw run workflow --progress # Show progress updates for long-running workflows ``` +After triggering a workflow, the command displays the workflow URL and suggests using `gh aw audit` to analyze the run. + **Options:** - `--repeat N`: Execute the workflow N times - `--use-local-secrets`: Temporarily push AI engine secrets from environment variables, then clean up +- `--progress`: Enable timer-based progress messages (emits elapsed time every 30 seconds to stderr) :::note[Codespaces] From GitHub Codespaces, grant `actions: write` and `workflows: write` permissions. See [Managing repository access](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces). @@ -274,7 +278,7 @@ gh aw logs workflow-name --repo owner/repo # Download logs from specific reposit | `--json` | Output structured metrics | `--json` | | `--repo owner/repo` | Download logs from specific repository | `--repo owner/repo` | -Downloads workflow execution logs, analyzes tool usage and network patterns, and caches results for faster subsequent runs (~10-100x speedup). +Downloads workflow execution logs, analyzes tool usage and network patterns, and caches results for faster subsequent runs (~10-100x speedup). The overview table includes columns for errors, warnings, missing tools, and noop messages. #### `audit` @@ -286,7 +290,7 @@ gh aw audit https://github.com/owner/repo/actions/runs/123 # By URL gh aw audit 12345678 --parse # Parse logs to markdown ``` -Provides detailed analysis including overview, execution metrics, tool usage patterns, MCP server failures, firewall analysis, and artifact information. Accepts run IDs or URLs from any repository and GitHub instance. +Provides detailed analysis including overview, execution metrics, tool usage patterns, MCP server failures, firewall analysis, noop messages, and artifact information. Accepts run IDs or URLs from any repository and GitHub instance. JSON output includes parsed noop messages similar to missing-tool reports. **GitHub Copilot Agent Detection:** Automatically detects GitHub Copilot agent runs and uses specialized log parsing to extract agent-specific metrics including turns, tool calls, errors, and token usage. Detection is based on workflow path (`copilot-swe-agent`) and agent-specific log patterns.