From c89ed2e793cc881b810c720ce692f892cd6d941d Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 18 Apr 2026 10:56:47 +0000 Subject: [PATCH] docs: document redirect frontmatter, allowed-base-branches, and new fix codemods - Add redirect: frontmatter field reference (gh aw update follows redirect chains; --no-redirect flag refuses redirected updates) - Document allowed-base-branches for create-pull-request safe output (enables per-run base branch override by the agent within policy-gated glob patterns) - Add steps-run-secrets-to-env and engine-env-secrets-to-engine-config codemods to gh aw fix reference (strict-mode secret leak remediation) Refs: #26903, #26916, #26919 Co-Authored-By: Claude Sonnet 4.6 --- docs/src/content/docs/reference/frontmatter.md | 17 +++++++++++++++++ .../reference/safe-outputs-pull-requests.md | 14 ++++++++++++++ docs/src/content/docs/setup/cli.md | 12 ++++++++++-- 3 files changed, 41 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md index e4783a71082..9ae9dda9b32 100644 --- a/docs/src/content/docs/reference/frontmatter.md +++ b/docs/src/content/docs/reference/frontmatter.md @@ -61,6 +61,23 @@ Tracks workflow origin in format `owner/repo/path@ref`. Automatically populated source: "githubnext/agentics/workflows/ci-doctor.md@v1.0.0" ``` +### Redirect (`redirect:`) + +Specifies a new canonical location when a workflow has been moved or renamed. When `gh aw update` encounters a workflow with a `redirect` field, it follows the redirect chain to the resolved location, rewrites the local `source` field to point to the new location, and emits a warning for each redirect hop. Redirect loops are detected and reported as errors. + +```yaml wrap +redirect: "githubnext/agentics/workflows/new-workflow-name.md@main" +``` + +Use `gh aw update --no-redirect` to refuse updates when the source workflow has a `redirect` field — the update fails rather than following the redirect. This is useful for auditing or when you want to explicitly control when redirects are followed. + +`gh aw compile` emits an informational message when a workflow has a `redirect` field configured, so the redirect is visible during local development. + +The `redirect` field uses the same `owner/repo/path@ref` format as `source:`. Redirect chains are followed transitively (up to a depth limit). + +> [!NOTE] +> The `redirect` field is set by workflow *authors* to signal that a workflow has moved. It is not typically set by end-users. If you see a redirect when running `gh aw update`, it means the upstream workflow has been relocated. + ### Private Workflows (`private:`) Mark a workflow as private to prevent it from being installed into other repositories via `gh aw add`. diff --git a/docs/src/content/docs/reference/safe-outputs-pull-requests.md b/docs/src/content/docs/reference/safe-outputs-pull-requests.md index c574a39333d..6d339a5a146 100644 --- a/docs/src/content/docs/reference/safe-outputs-pull-requests.md +++ b/docs/src/content/docs/reference/safe-outputs-pull-requests.md @@ -41,6 +41,9 @@ safe-outputs: target-repo: "owner/repo" # cross-repository allowed-repos: ["org/repo1", "org/repo2"] # additional allowed repositories base-branch: "vnext" # target branch for PR (default: github.base_ref || github.ref_name) + allowed-base-branches: # allow agent to override base branch at runtime (glob patterns) + - main + - release/* fallback-as-issue: false # disable issue fallback (default: true) auto-close-issue: false # don't auto-add "Fixes #N" to PR description (default: true) preserve-branch-name: true # omit random salt suffix from branch name (default: false) @@ -54,6 +57,17 @@ safe-outputs: The `base-branch` field specifies which branch the pull request should target. This is particularly useful for cross-repository PRs where you need to target non-default branches (e.g., `vnext`, `release/v1.0`, `staging`). When not specified, defaults to `github.base_ref` (the PR's target branch) with a fallback to `github.ref_name` (the workflow's branch) for push events. +The `allowed-base-branches` field enables per-run base branch overrides by the agent at runtime. When configured, the agent may supply a `base` field in the `create_pull_request` tool call to target a branch other than the compiled `base-branch`. The override is accepted only when it matches one of the configured glob patterns (e.g., `main`, `release/*`). Without `allowed-base-branches`, only the compiled `base-branch` is used regardless of what the agent requests. This is useful when agent-computed data (such as a version string or user request) determines the target branch at runtime: + +```yaml wrap +safe-outputs: + create-pull-request: + base-branch: main + allowed-base-branches: + - main + - release/* +``` + **Example use case:** A workflow in `org/engineering` that creates PRs in `org/docs` targeting the `vnext` branch for feature documentation: ```yaml wrap diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md index 185ffa6b33c..8d61e59297c 100644 --- a/docs/src/content/docs/setup/cli.md +++ b/docs/src/content/docs/setup/cli.md @@ -239,7 +239,13 @@ gh aw fix --list-codemods # List available codemods **Options:** `--write`, `--list-codemods` -Notable codemods include `expires-integer-to-string`, which converts bare integer `expires` values (e.g., `expires: 7`) to the preferred day-string format (e.g., `expires: 7d`) in all `safe-outputs` blocks. Run `gh aw fix --list-codemods` to see all available codemods. +Available codemods include: + +- `expires-integer-to-string` — converts bare integer `expires` values (e.g., `expires: 7`) to the preferred day-string format (e.g., `expires: 7d`) in all `safe-outputs` blocks. +- `steps-run-secrets-to-env` — rewrites inline `${{ secrets.NAME }}` interpolations in step `run:` commands to `$NAME` and adds step-level `env` bindings. Required for strict-mode compliance. +- `engine-env-secrets-to-engine-config` — removes secret-bearing entries from `engine.env` that are unsafe under strict mode, preserving required engine credential keys. + +Run `gh aw fix --list-codemods` to see all available codemods. #### `compile` @@ -552,7 +558,9 @@ gh aw update --disable-release-bump # Update workflows; only force-update gh aw update --create-pull-request # Update and open a pull request ``` -**Options:** `--dir`, `--no-merge`, `--major`, `--force`, `--engine`, `--no-stop-after`, `--stop-after`, `--disable-release-bump`, `--create-pull-request`, `--no-compile` +**Options:** `--dir`, `--no-merge`, `--major`, `--force`, `--engine`, `--no-stop-after`, `--stop-after`, `--disable-release-bump`, `--create-pull-request`, `--no-compile`, `--no-redirect` + +The `--no-redirect` flag causes `update` to fail when the source workflow has a [`redirect`](/gh-aw/reference/frontmatter/#redirect) field, rather than following the redirect to its new location. Use this when you want explicit control over redirect handling. #### `upgrade`