Skip to content

[docs] Update documentation for features merged April 15, 2026 #26399

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
Apr 15, 2026
+22 −4
Merged

[docs] Update documentation for features merged April 15, 2026 #26399

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
18 changes: 17 additions & 1 deletion docs/src/content/docs/reference/safe-outputs-pull-requests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -275,14 +275,30 @@ This protects against supply chain attacks where an AI agent could inadvertently

### Policy Options

Configure the `protected-files` field on either safe output:
The `protected-files` field accepts either a string policy value or an object with a `policy` and an `exclude` list.

**String form** — set a single policy for all protected files:

| Value | Behaviour |
|-------|-----------|
| `blocked` (default) | Hard-block: the safe output fails with an error |
| `fallback-to-issue` | Create a review issue with instructions for the human to apply or reject the changes manually |
| `allowed` | No restriction — all protected file changes are permitted. **Use only when the workflow is explicitly designed to manage these files.** |

**Object form** — set a policy and exclude specific files from the protected set:

```yaml wrap
safe-outputs:
create-pull-request:
protected-files:
policy: fallback-to-issue # same values as string form (default: blocked)
exclude:
- AGENTS.md # allow the agent to update its own instruction file
- .agents/ # allow updates to the .agents/ directory
```

The `exclude` list names files by **basename** (e.g., `AGENTS.md`) or **path prefix** (e.g., `.agents/`) to remove from the default protected set. The remaining protected files still enforce the configured policy. This is useful when a workflow is explicitly designed to manage one specific instruction file without disabling all protection.

**`create-pull-request` with `fallback-to-issue`**: the branch is pushed normally, then a review issue is created with a PR creation intent link, a `[!WARNING]` banner explaining why the fallback was triggered, and instructions to review carefully before creating the PR.

**`push-to-pull-request-branch` with `fallback-to-issue`**: instead of pushing to the PR branch, a review issue is created with the target PR link, patch download/apply instructions, and a review warning.
Expand Down
8 changes: 5 additions & 3 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 @@ -257,7 +257,9 @@ gh aw compile --dependabot # Generate dependency manifests
gh aw compile --purge # Remove orphaned .lock.yml files
```

**Options:** `--validate`, `--strict`, `--fix`, `--zizmor`, `--dependabot`, `--json`, `--no-emit`, `--watch`, `--purge`, `--stats`
**Options:** `--validate`, `--strict`, `--fix`, `--zizmor`, `--dependabot`, `--json`, `--no-emit`, `--watch`, `--purge`, `--stats`, `--approve`

**`--approve` flag:** When compiling a workflow that already has a lock file, the compiler enforces *safe update mode* — any newly added secrets or custom actions not present in the previous manifest require explicit approval. Pass `--approve` to accept these changes and regenerate the manifest baseline. On first compile (no existing lock file), enforcement is skipped automatically and `--approve` is not needed.

**Error Reporting:** Displays detailed error messages with file paths, line numbers, column positions, and contextual code snippets.

Expand Down Expand Up @@ -318,7 +320,7 @@ 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`, `--enable-if-needed`, `--json/-j`, `--auto-merge-prs`, `--dry-run`, `--engine/-e`, `--raw-field/-F`, `--repo/-r`
**Options:** `--repeat`, `--push` (see [--push flag](#the---push-flag)), `--ref`, `--enable-if-needed`, `--json/-j`, `--auto-merge-prs`, `--dry-run`, `--engine/-e`, `--raw-field/-F`, `--repo/-r`, `--approve`

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

Expand Down Expand Up @@ -564,7 +566,7 @@ gh aw upgrade --audit # Run dependency health audit
gh aw upgrade --audit --json # Dependency audit in JSON format
```

**Options:** `--dir/-d`, `--no-fix`, `--no-actions`, `--no-compile`, `--create-pull-request`, `--audit`, `--json/-j`
**Options:** `--dir/-d`, `--no-fix`, `--no-actions`, `--no-compile`, `--create-pull-request`, `--audit`, `--json/-j`, `--approve`

### Advanced

Expand Down