diff --git a/.claude/skills/gh-aw-guide/SKILL.md b/.claude/skills/gh-aw-guide/SKILL.md index 668c18eb49..26b6b9a4c1 100644 --- a/.claude/skills/gh-aw-guide/SKILL.md +++ b/.claude/skills/gh-aw-guide/SKILL.md @@ -14,7 +14,7 @@ description: >- This skill provides a complete reference for building, securing, and maintaining GitHub Agentic Workflows. It covers the gh-aw platform's architecture, security model, and all available features. -> **Version baseline:** This guide covers features through **v0.71.1**. A fresh `gh extension install github/gh-aw` gets the latest release. Features introduced after v0.68.3 are marked with their minimum version (e.g., `(v0.70.0+)`). Verify your compiler version with `gh aw --version` and upgrade if needed: `gh extension install github/gh-aw --pin `. +> **Version baseline:** This guide covers features through **v0.71.4**. A fresh `gh extension install github/gh-aw` gets the latest release. Features introduced after v0.68.3 are marked with their minimum version (e.g., `(v0.70.0+)`). Verify your compiler version with `gh aw --version` and upgrade if needed: `gh extension install github/gh-aw --pin `. ## Quick Start @@ -85,6 +85,7 @@ gh aw upgrade # Upgrade gh-aw CLI extension | Replying to inline review comments manually | `reply-to-pull-request-review-comment` safe output — threads replies under existing review comments | [Safe Outputs](https://github.github.com/gh-aw/reference/safe-outputs-pull-requests/) | | Resolving review threads manually | `resolve-pull-request-review-thread` safe output — marks review threads as resolved | [Safe Outputs](https://github.github.com/gh-aw/reference/safe-outputs-pull-requests/) | | Configuring the GitHub CLI proxy mode | `tools.github.mode: gh-proxy` (v0.70.0+) — official config; old `cli-proxy` feature flag is deprecated | [Engines](https://github.github.com/gh-aw/reference/engines/) | +| Using `{{#import}}` directives in workflow body | `{{#runtime-import}}` (v0.71.2+) — `{{#import}}` is deprecated; resolved at both compile and runtime | [Imports](https://github.github.com/gh-aw/reference/imports/) | | `slash_command:` without `events:` filter (subscribes to ALL comment events) | `events: [pull_request_comment]` or `events: [issue_comment]` | [Command Triggers](https://github.github.com/gh-aw/reference/command-triggers/) | | `cancel-in-progress: true` on `slash_command:` workflows | `cancel-in-progress: false` — non-matching events cancel in-progress agent runs | [Concurrency](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency) | | Using `pull_request` trigger for agentic workflows | `slash_command:` or `schedule` — `pull_request` causes the "Approve and run" gate for ALL workflows | [Triggers](https://github.github.com/gh-aw/reference/triggers/) | @@ -370,6 +371,10 @@ safe-outputs: **6. XPIA hardening (v0.70.0+)** — Cross-prompt injection (XPIA) sanitization paths have been hardened. `disable-xpia-prompt` is now **rejected at compile time in strict mode** — do not use it. If a workflow previously relied on it, remove the flag; the runtime handles XPIA protection by default. +**7. `pull_request_target` security validation (v0.71.4+)** — The compiler now validates `pull_request_target` usage and detects common pwn-request patterns automatically. Detected issues are flagged at compile time. Ensure workflows compiled before v0.71.4 are recompiled to benefit from the new checks. + +**8. Bot-filtering confused deputy guard (v0.71.4+)** — The `skip-bots:` filter now guards against dependabot confused deputy attacks. Previously, a dependabot PR could be crafted to bypass bot filtering via indirect trigger paths. The fix is automatic; no workflow changes required, but recompile to get the updated guard logic. + ### Idempotency and the Edited-Comment Time-Bomb **Slash command workflows MUST be idempotent.** Treat every activation as if the same command might already be running for the same target. Check before acting, claim a lock, no-op if already in progress or done. @@ -503,6 +508,41 @@ on: **`comment_memory` safe output (v0.69.2+)** — Agents can persist structured memory in a managed issue/PR comment. Memory files are materialized under `/tmp/gh-aw/comment-memory/` before the agent runs and synced back after. Enables stateful agents across runs without external storage. +**`on.labels:` filter (v0.71.4+)** — Filter trigger events by labels on the issue/PR. The workflow only fires when the issue or PR has all the specified labels: + +```yaml +on: + slash_command: + name: review + labels: [approved-for-agent] # Only fire when this label is present +``` + +**`engine.mcp.session-timeout` (v0.71.3+)** — Set the MCP gateway session timeout (in seconds) to control how long MCP sessions stay alive. Prevents premature timeouts in long-running workflows: + +```yaml +engine: + id: copilot + mcp: + session-timeout: 600 # 10 minutes (default: 300) +``` + +**Parameterized safe-outputs for `workflow_call` (v0.71.3+)** — `workflow_call` inputs can now control `safe-outputs.threat-detection`, boolean flags, PR policy fields, and list constraints. Build reusable workflows callers can configure without forking: + +```yaml +# In the reusable workflow +on: + workflow_call: + inputs: + enable_threat_detection: + type: boolean + default: true + +safe-outputs: + threat-detection: ${{ inputs.enable_threat_detection }} +``` + +**Auto-inject `create_issue` safe output (v0.71.3+)** — Workflows without explicit safe-output configuration now automatically get a `create_issue` safe output. This reduces boilerplate for simple workflows that only need to create issues. + **`on.needs:` (v0.70.0+)** — Express dependencies on custom `pre_activation`/`activation` jobs, enabling GitHub App credentials to be sourced from upstream job outputs. See also `safe-outputs.needs` (v0.69.1+) for credential-supply dependencies in the safe-outputs job. **`merge-pull-request` safe output (v0.70.0+)** — Merge a PR directly as a safe output. Executes in the safe-outputs job with proper write permissions, not inside the agent container. @@ -515,6 +555,14 @@ tools: mode: gh-proxy ``` +**COPILOT_PROVIDER_* / BYOK support (v0.71.4+)** — `COPILOT_PROVIDER_*` environment variables are now in the strict-mode allowlist, and token validation is skipped in BYOK (Bring Your Own Key) mode. This enables workflows using custom LLM providers. + +**`` in safe-outputs HTML allowlist (v0.71.4+)** — The `` HTML tag is now allowed in safe-output markdown content (comments, issue bodies, PR descriptions). Previously only text-level HTML was permitted. + +**`tools.bash` parameterized (v0.71.3+)** — The `tools.bash` configuration can now be parameterized via `workflow_call` inputs for greater reusable-workflow flexibility. + +**`add_reviewer` team reviewers (v0.71.3+)** — The `add_reviewer` MCP tool now supports `team_reviewers` to request reviews from GitHub teams (not just individuals). + **Claude engine (v0.71.0+)** — The Claude engine has two permission modes: `acceptEdits` (default — agent proposes edits that the safe-outputs layer validates) and `bypassPermissions` (activated when unrestricted bash `bash: "*"` is granted — agent executes directly). v0.71.0 updated the internal wiring; recompile Claude-engine workflows compiled with older versions. **`checkout: false`** — Skip the default repository checkout when the workflow doesn't need source code (e.g., ChatOps commands that only call APIs via `web-fetch`). Saves ~10-30s of runner time. diff --git a/.claude/skills/gh-aw-guide/references/architecture.md b/.claude/skills/gh-aw-guide/references/architecture.md index c0649c0bc5..c463b33921 100644 --- a/.claude/skills/gh-aw-guide/references/architecture.md +++ b/.claude/skills/gh-aw-guide/references/architecture.md @@ -53,6 +53,8 @@ The prompt is built in the **activation job** via `{{#runtime-import .github/wor - The agent prompt is always the base branch version — fork PRs cannot alter it - The prompt references files on disk (e.g., `SKILL.md`) — those files must exist in the agent's workspace +> **`{{#import}}` deprecation (v0.71.2+):** The `{{#import}}` directive is deprecated in favor of `{{#runtime-import}}`. Both are still resolved at compile time and runtime, but `{{#import}}` will be removed in a future release. Migrate existing workflows: replace `{{#import path}}` with `{{#runtime-import path}}`. + ### Fork PR Activation Gate By default, `gh aw compile` automatically injects a fork guard into the activation job's `if:` condition: `head.repo.id == repository_id`. This blocks fork PRs on `pull_request` events. @@ -352,6 +354,12 @@ Safe outputs enforce security through separation: agents run read-only and reque - `team-reviewers: [platform-reviewers]` — Request team reviews - `max: 3` — Multiple PRs per run (each on its own branch) +**`push-to-pull-request-branch` notable options:** +- `check-branch-protection: true` (v0.71.2+) — Verify branch protection is enabled before pushing; fails safely if not configured +- Cross-repo support (v0.71.2+) — No longer limited to same-repo; configure for cross-repository push targets. Recompile affected workflows. + +**Threat detection behavior:** When threat detection fires, a **CAUTION alert is injected at the top** of the output markdown content and an `agentic-threat-detected` label is applied to the PR/issue (v0.71.2+). This makes threats clearly visible in the GitHub UI. + **`submit-pull-request-review` notable options:** - `allowed-events: [COMMENT]` — Blocks APPROVE; non-blocking reviews. **Always use this** unless you need merge-gating. - `allowed-events: [COMMENT, REQUEST_CHANGES]` — Blocking reviews. Pair with `supersede-older-reviews: true`. @@ -419,3 +427,6 @@ These issues are now **all closed** — documented here for historical context: | Hundreds of "skipped" runs per day | `slash_command:` default subscribes to ALL comment events | Narrow `events:` field; accept remaining noise as cost of low-latency invocation | | `label_command:` denies triage users | `triage` role not in default `on.roles:` allowlist | Add `roles: [admin, maintainer, write, triage]` | | Forked workflows fire unexpectedly in forks | Workflows copied to fork run on routine events inside the fork | Add job-level guard: `if: github.event.repository.fork == false \|\| github.event_name == 'workflow_dispatch'` | +| MCP connection drops in long-running workflows | Default MCP session timeout too short | Set `engine.mcp.session-timeout: 600` (or higher) in frontmatter (v0.71.3+) | +| Copilot driver fails with null-type tool_call error | Null-type tool_call 400 error poisons conversation history | Driver automatically restarts fresh instead of `--continue` (v0.71.3+); recompile if hitting this issue | +| `gh aw run --repeat` times out after 30 minutes | Old CLI wait limit | Upgrade to v0.71.3+ — wait time now matches the 6-hour GitHub Actions maximum | diff --git a/.github/instructions/gh-aw-workflows.sync.yaml b/.github/instructions/gh-aw-workflows.sync.yaml index eee665c68b..6766477072 100644 --- a/.github/instructions/gh-aw-workflows.sync.yaml +++ b/.github/instructions/gh-aw-workflows.sync.yaml @@ -74,7 +74,7 @@ sources: # GitHub releases — check for new versions - releases: github/gh-aw - last_reviewed_release: v0.71.1 + last_reviewed_release: v0.71.4 style: | Match existing section structure. Use tables for feature comparisons.