Skip to content

[docs] Update documentation for features from 2026-03-10 #20306

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 1 commit into from
Mar 10, 2026
Merged

[docs] Update documentation for features from 2026-03-10 #20306

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
12 changes: 12 additions & 0 deletions docs/src/content/docs/reference/safe-outputs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1220,6 +1220,18 @@ jobs:
- run: echo "Created issue ${{ needs.run-agent.outputs.created_issue_number }}"
```

### Failure Issue Reporting (`report-failure-as-issue:`)

Controls whether workflow failures are reported as GitHub issues (default: `true`). Set to `false` to suppress automatic failure issue creation for a specific workflow.

```yaml wrap
safe-outputs:
report-failure-as-issue: false
create-issue:
```

This mirrors the `noop.report-as-issue` pattern. Use this to silence noisy failure reports for workflows where failures are expected or handled externally.
Copy link

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

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

This section references the noop.report-as-issue pattern, but the earlier “No-Op Logging (noop:)” section doesn’t document report-as-issue, so readers won’t know what that comparison means. Either add a short explanation/link to the noop option, or rephrase without relying on an undocumented setting.

Copilot uses AI. Check for mistakes.

### Group Reports (`group-reports:`)

Controls whether failed workflow runs are grouped under a parent "[aw] Failed runs" issue. This is opt-in and defaults to `false`.
Expand Down
35 changes: 30 additions & 5 deletions docs/src/content/docs/setup/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,9 +126,23 @@ gh aw add ci-doctor --create-pull-request # Create PR instead of commit
Create a workflow template in `.github/workflows/`. Opens for editing automatically.

```bash wrap
gh aw new # Interactive mode
gh aw new my-custom-workflow # Create template (.md extension optional)
gh aw new my-workflow --force # Overwrite if exists
gh aw new # Interactive mode
gh aw new my-custom-workflow # Create template (.md extension optional)
gh aw new my-workflow --force # Overwrite if exists
gh aw new my-workflow --engine claude # Inject engine into frontmatter
```

**Options:** `--force`, `--engine/-e`

When `--engine` is specified, the engine is injected into the generated frontmatter template:

```yaml wrap
---
permissions:
contents: read
engine: claude
network: defaults
...
Comment on lines +139 to +145
Copy link

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

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

In this frontmatter example, the closing line uses ..., which is a YAML document end marker but not the standard Markdown frontmatter delimiter. For consistency with other workflow examples (which use --- to close frontmatter), consider replacing ... with --- or using a comment (e.g., # ...) to indicate omitted fields so readers don't copy an invalid frontmatter block.

Copilot uses AI. Check for mistakes.
```

#### `secrets`
Expand Down Expand Up @@ -251,9 +265,12 @@ gh aw run workflow1 workflow2 # Run multiple workflows
gh aw run workflow --repeat 3 # Repeat 3 times
gh aw run workflow --push # Auto-commit, push, and dispatch workflow
gh aw run workflow --push --ref main # Push to specific branch
gh aw run workflow --json # Output triggered workflow results as JSON
```

**Options:** `--repeat`, `--push` (see [--push flag](#the---push-flag)), `--ref`, `--auto-merge-prs`, `--enable-if-needed`
**Options:** `--repeat`, `--push` (see [--push flag](#the---push-flag)), `--ref`, `--auto-merge-prs`, `--enable-if-needed`, `--json/-j`

When `--json` is set, a JSON array of triggered workflow results is written to stdout.

When `--push` is used, automatically recompiles outdated `.lock.yml` files, stages all transitive imports, and triggers workflow run after successful push. Without `--push`, warnings are displayed for missing or outdated lock files.

Expand All @@ -272,9 +289,12 @@ gh aw list # List all workflows
gh aw list ci- # Filter by pattern (case-insensitive)
gh aw list --json # Output in JSON format
gh aw list --label automation # Filter by label
gh aw list --dir custom/workflows # List from custom directory
```

**Options:** `--json`, `--label`
**Options:** `--json`, `--label`, `--dir/-d`

The `--dir` flag overrides the local workflow directory. It applies only when `--repo` is not set, consistent with other commands such as `validate`, `fix`, and `add`.
Comment on lines +295 to +297
Copy link

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

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

The list command supports remote listing via --repo/-r and --path (see pkg/cli/list_workflows_command.go:41-76), but this section’s options list omits those flags while the text references --repo. Consider adding --repo/-r (and --path) to the documented options/examples so readers can actually use --dir vs --path correctly for local vs remote repos.

Copilot uses AI. Check for mistakes.

Fast enumeration without GitHub API queries. For detailed status including enabled/disabled state and run information, use `status` instead.

Expand Down Expand Up @@ -322,8 +342,13 @@ gh aw audit https://github.com/owner/repo/actions/runs/123 # By workflow run URL
gh aw audit https://github.com/owner/repo/actions/runs/123/job/456 # By job URL (extracts first failing step)
gh aw audit https://github.com/owner/repo/actions/runs/123/job/456#step:7:1 # By step URL (extracts specific step)
gh aw audit 12345678 --parse # Parse logs to markdown
gh aw audit 12345678 --repo owner/repo # Specify repository for bare run ID
```

**Options:** `--parse`, `--json`, `--repo/-r`

The `--repo` flag accepts `owner/repo` format and is required when passing a bare numeric run ID without a full URL, allowing the command to locate the correct repository.
Copy link

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

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

This paragraph says --repo is required when passing a bare numeric run ID, but audit can resolve {owner}/{repo} from the current repo context when owner/repo aren’t provided (see fetchWorkflowRunMetadata in pkg/cli/audit.go:614-620). Suggest rewording to clarify that --repo is only needed when auditing a run outside the current repository context (or when the run ID alone is ambiguous).

Copilot uses AI. Check for mistakes.

Logs are saved to `logs/run-{id}/` with filenames indicating the extraction level. Pre-agent failures (lockdown validation, missing secrets, binary install) surface the actual error in `failure_analysis.error_summary`. Invalid run IDs return a human-readable error.

#### `health`
Expand Down