From 609d02ff17a57ed913d231a93c5ca27a7b53aaad Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sun, 16 Aug 2026 08:59:05 +0000 Subject: [PATCH] Sync instruction files with release v0.87.0 Accuracy fixes: - syntax-engine.md: bare mode is only supported by copilot/claude, not codex/gemini (codex/gemini never set BareMode in EngineCapabilities); document crush/aider/goose/custom import-based engines alongside opencode/cursor/kiro/deepseek-harness - safe-outputs-automation.md + syntax-agentic.md: document the approve-workflow-run safe output (ApproveWorkflowRunConfig), which had no coverage anywhere in .github/aw/ - syntax-agentic.md: document ambient-folders and threat-detection-suppress top-level schema fields, present in main_workflow_schema.json but undocumented Duplication cleanup: - Consolidated the trigger-selection quick-reference tables in github-agentic-workflows.md and create-agentic-workflow.md into a single pointer to triggers.md's Decision Matrix - Consolidated the frontmatter-vs-body recompilation rule in github-agentic-workflows.md and update-agentic-workflow.md into a pointer to workflow-editing.md Co-Authored-By: Claude Sonnet 5 --- .github/aw/create-agentic-workflow.md | 12 +----------- .github/aw/github-agentic-workflows.md | 18 +++--------------- .github/aw/safe-outputs-automation.md | 13 +++++++++++++ .github/aw/syntax-agentic.md | 11 ++++++++++- .github/aw/syntax-engine.md | 3 ++- .github/aw/update-agentic-workflow.md | 5 +---- 6 files changed, 30 insertions(+), 32 deletions(-) diff --git a/.github/aw/create-agentic-workflow.md b/.github/aw/create-agentic-workflow.md index 716812fbc25..9cfaf555785 100644 --- a/.github/aw/create-agentic-workflow.md +++ b/.github/aw/create-agentic-workflow.md @@ -144,17 +144,7 @@ When evaluating scenarios, classify any failure before stopping: ### 2. Choose the trigger -Use the smallest trigger that matches the request. - -Common mappings: - -- issue automation → `on: issues:` -- pull request automation → `on: pull_request:` -- scheduled reporting → fuzzy `schedule:` such as `daily on weekdays` -- on-demand comments → `slash_command` -- UI-driven actions → `label_command` -- GitHub Actions pipeline monitoring → `workflow_run` -- external deployment monitoring → `deployment_status` +Use the smallest trigger that matches the request. See the [Decision Matrix](triggers.md#decision-matrix) in triggers.md for the base trigger-to-use-case mapping. | Scenario | Trigger and default output | Details | |---|---|---| diff --git a/.github/aw/github-agentic-workflows.md b/.github/aw/github-agentic-workflows.md index ab54b707166..06f7ce29379 100644 --- a/.github/aw/github-agentic-workflows.md +++ b/.github/aw/github-agentic-workflows.md @@ -57,10 +57,7 @@ Natural language instructions for the AI agent. ## Recompilation Rule -- Edit the **frontmatter** → run `gh aw compile `. -- Edit the **markdown body** only → no recompilation required. - -See also: [workflow-editing.md](workflow-editing.md) +See [workflow-editing.md](workflow-editing.md) for when `gh aw compile` is required. ## Core Rules @@ -78,18 +75,9 @@ Use `@.github/aw/instructions.md` as the canonical repository-local overlay for - Installed gh-aw agents should load and apply it automatically when present. - Precedence: apply upstream defaults first, then apply repository overlay rules; when they conflict, repository overlay rules win. -## Trigger Selection Quick Reference - -Use the smallest trigger that matches the requested automation. - -| Need | Trigger | Notes | -|---|---|---| -| Review pull request changes or UI diffs | `pull_request` | Use for PR-scoped analysis, comments, and optional `playwright`-based visual regression. | -| React to the result of another GitHub Actions workflow | `workflow_run` | Scope `workflows:` explicitly, use `types: [completed]`, and gate conclusions before creating incidents. | -| Publish recurring reports or stakeholder digests | `schedule` | Define the exact reporting window and default to `create-issue`; add `workflow_dispatch` when manual reruns are useful. | -| Run the workflow on demand | `workflow_dispatch` | Use for manual tests, backfills, and operator-invoked runs; often pair with `schedule` or `workflow_run`. | +## Trigger Selection -See also: [workflow-constraints.md](workflow-constraints.md) +Use the smallest trigger that matches the requested automation. See the [Decision Matrix](triggers.md#decision-matrix) in triggers.md for the canonical trigger-to-use-case mapping, and [workflow-constraints.md](workflow-constraints.md) for the security posture. ## Ad Hoc Scenario Evaluation diff --git a/.github/aw/safe-outputs-automation.md b/.github/aw/safe-outputs-automation.md index aac49a28fff..4ac30fc3b14 100644 --- a/.github/aw/safe-outputs-automation.md +++ b/.github/aw/safe-outputs-automation.md @@ -243,6 +243,19 @@ description: Safe-output reference for workflow dispatch, code scanning, checks, ``` Agent calls `set_issue_field` with `value` plus either `field_name` (preferred) or `field_node_id`. `issue_number` is optional and defaults to the triggering issue. +- `approve-workflow-run:` - Approve a pending workflow run from a fork pull request + + ```yaml + safe-outputs: + approve-workflow-run: + allowed-workflows: [ci.yml] # Required: workflow filenames eligible for approval (no paths) + fork: true # Optional: restrict to fork pull requests (default: false) + allowed-pull-requests: ["123"] # Optional: restrict to specific PR numbers + protected-files: blocked # Optional: "blocked" (default), "fallback-to-issue", or "allowed" + github-token: ${{ secrets.APPROVE_WORKFLOW_RUN_TOKEN }} # Required: external token/app (github.token cannot approve fork PR runs) + ``` + + Requires `actions: write` (added automatically) plus an external `github-token` or `github-app` — the default `github.token` is not permitted to approve workflow runs for fork pull requests. - `noop:` - Log completion message for transparency (auto-enabled) ```yaml diff --git a/.github/aw/syntax-agentic.md b/.github/aw/syntax-agentic.md index 55a0662074b..cdb03607698 100644 --- a/.github/aw/syntax-agentic.md +++ b/.github/aw/syntax-agentic.md @@ -129,6 +129,15 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor - **`resources:`** - Additional workflow or action files fetched alongside this workflow when running `gh aw add` (array). Entries are relative paths from the same directory to `.md` or `.yml`/`.yaml` files. - Example: `resources: [shared/tool-setup.md, shared/mcp/tavily.md]` +- **`threat-detection-suppress:`** - Auditable false-positive suppression annotations for compiler threat-detection rules (array of objects) + - Each entry requires `rule:` (a `CTR-###` identifier) and `reason:` (non-empty string); optional `expires:` (ISO-8601 date) + - Example: `threat-detection-suppress: [{ rule: CTR-025, reason: "reviewed false positive", expires: "2026-12-31" }]` + +- **`ambient-folders:`** - Workspace-relative folders bundled into the activation artifact and restored before the agent runs (array of strings) + - Useful for activation steps that generate reusable prompt, skill, or agent context ahead of the agent job + - Merges with `ambient-folders` declared by imported workflows + - Example: `ambient-folders: [".claude/skills", ".github/agents"]` + - **`tracker-id:`** - Optional identifier to tag all created assets (string) - Must be at least 8 characters and contain only alphanumeric characters, hyphens, and underscores - This identifier is inserted in the body/description of all created assets (issues, discussions, comments, pull requests) @@ -323,7 +332,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor - **`tools:`** - Tool configuration for the coding agent (`github`, `agentic-workflows`, `edit`, `web-fetch`, `web-search`, `bash`, `playwright`, custom MCP server names, plus `timeout`/`startup-timeout`/`cli-proxy`). See [syntax-tools-imports.md](syntax-tools-imports.md#tool-configuration) for the full schema (GitHub `mode`/`toolsets`/integrity fields, bash allowlist decision rule, Playwright CLI mode). -- **`safe-outputs:`** - Safe output processing configuration. See [safe-outputs.md](safe-outputs.md) for complete documentation of all output types: `create-issue`, `create-discussion`, `add-comment`, `create-pull-request`, `push-to-pull-request-branch`, `close-issue`, `close-discussion`, `update-issue`, `update-pull-request`, `add-labels`, `remove-labels`, `replace-label`, `dispatch-workflow`, `call-workflow`, `create-code-scanning-alert`, `upload-asset`, `upload-artifact`, `assign-to-agent`, `assign-to-user`, and more. +- **`safe-outputs:`** - Safe output processing configuration. See [safe-outputs.md](safe-outputs.md) for complete documentation of all output types: `create-issue`, `create-discussion`, `add-comment`, `create-pull-request`, `push-to-pull-request-branch`, `close-issue`, `close-discussion`, `update-issue`, `update-pull-request`, `add-labels`, `remove-labels`, `replace-label`, `dispatch-workflow`, `call-workflow`, `create-code-scanning-alert`, `upload-asset`, `upload-artifact`, `assign-to-agent`, `assign-to-user`, `approve-workflow-run`, and more. **Key safe-outputs global fields** (detail in [safe-outputs-runtime.md](safe-outputs-runtime.md)): `github-token`, `github-app`, `staged` (preview mode, no API calls), `footer`, `threat-detection`, `runs-on` (default `ubuntu-slim`), `messages`, `env`, `max-patch-size` (KB, default `4096`). diff --git a/.github/aw/syntax-engine.md b/.github/aw/syntax-engine.md index 5a062d112bb..7b035c69367 100644 --- a/.github/aw/syntax-engine.md +++ b/.github/aw/syntax-engine.md @@ -12,6 +12,7 @@ See [syntax-agentic.md](syntax-agentic.md) for the full frontmatter field index. - The experimental `deepseek-harness` engine is available through `imports: [shared/deepseek-harness.md]`; see [`smoke-deepseek-harness.md`](../workflows/smoke-deepseek-harness.md) for an example. It runs the developer-preview `dsh` headless profile with AWF provider routing and uses `provider/model` syntax. - The experimental `cursor` engine is available through `imports: [shared/cursor.md]`; see [`smoke-cursor.md`](../workflows/smoke-cursor.md) for an example. Requires the `CURSOR_API_KEY` secret. Cursor reads project rules from `.cursor/rules/*.mdc` and respects the root-level `.cursorignore` and `AGENTS.md`; both are protected in the manifest. Use `model: cursor/auto` or a specific model such as `cursor/claude-3-7-sonnet`. - The experimental `kiro` engine is available through `imports: [shared/kiro.md]`; see [`smoke-kiro.md`](../workflows/smoke-kiro.md) for an example. Requires the `KIRO_API_KEY` secret. Kiro reads steering documents from `.kiro/steering/` and hook definitions from `.kiro/hooks/`; these directories and `AGENTS.md` are protected in the manifest. Model must use `kiro/` prefix, e.g. `model: kiro/claude-sonnet-4-5`. + - The experimental `crush`, `aider`, `goose`, and `custom` (GenAIScript) engines are also available through `imports: [shared/.md]`; see [`smoke-crush.md`](../workflows/smoke-crush.md), [`smoke-aider.md`](../workflows/smoke-aider.md), and [`smoke-goose.md`](../workflows/smoke-goose.md) for examples. Full list of import-based engines: see `.github/aw/engines.json`. - Object format for extended configuration: ```yaml @@ -29,7 +30,7 @@ See [syntax-agentic.md](syntax-agentic.md) for the full frontmatter field index. args: ["--verbose"] # Optional: custom CLI arguments injected before prompt (array) api-target: api.acme.ghe.com # Optional: custom API endpoint hostname for GHEC/GHES (hostname only, no protocol/path) command: /usr/local/bin/copilot # Optional: override default engine executable (skips installation) - bare: true # Optional: disable automatic context loading (copilot: --no-custom-instructions; claude: --bare; codex: --no-system-prompt; gemini: GEMINI_SYSTEM_MD=/dev/null). Default: false + bare: true # Optional: disable automatic context loading. Only supported by 'copilot' (--no-custom-instructions) and 'claude' (--bare); ignored with a warning on other engines. Default: false user-agent: "myapp/1.0" # Optional: custom user agent string (codex engine only) config: | # Optional: additional TOML config appended to config.toml (codex engine only) [extra] diff --git a/.github/aw/update-agentic-workflow.md b/.github/aw/update-agentic-workflow.md index 018586ff6f1..c8908f6529d 100644 --- a/.github/aw/update-agentic-workflow.md +++ b/.github/aw/update-agentic-workflow.md @@ -36,10 +36,7 @@ This prompt is for **updating existing workflows only**. For new workflows, use ## First Decision: Frontmatter or Prompt Body? -Use [workflow-editing.md](workflow-editing.md) as the source of truth. - -- frontmatter change → recompilation required -- markdown-body-only change → no recompilation required for runtime behavior, but always compile to keep `.lock.yml` in sync +Use [workflow-editing.md](workflow-editing.md) as the source of truth for when recompilation is required. Always compile after any edit to keep `.lock.yml` in sync, even for body-only changes. ## Update Rules