From 09b29fe7b3eb79a7bd8c4f62b2b853fb28a06367 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 23 Mar 2026 04:27:25 +0000 Subject: [PATCH] docs: update documentation for 2026-03-23 - Fix broken architecture link in index.mdx (closes #22226) - Add dispatch_repository safe-output type documentation (from #22315) - Add engine feature comparison table to engines reference (closes #22147) - Add frontmatter common field name mistakes to troubleshooting (addresses #22092) Co-Authored-By: Claude Sonnet 4.6 --- docs/src/content/docs/index.mdx | 2 +- docs/src/content/docs/reference/engines.md | 20 ++++++++ .../content/docs/reference/safe-outputs.md | 50 +++++++++++++++++++ .../docs/troubleshooting/common-issues.md | 17 +++++++ 4 files changed, 88 insertions(+), 1 deletion(-) diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 88f6301f296..8ce1785ffe9 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -44,7 +44,7 @@ Developed by GitHub Next and Microsoft Research, workflows run with added guardr Deep integration with Actions, Issues, PRs, Discussions, and repository management - + Sandboxed execution with minimal permissions and safe output processing diff --git a/docs/src/content/docs/reference/engines.md b/docs/src/content/docs/reference/engines.md index ece20830346..b1abcab92f3 100644 --- a/docs/src/content/docs/reference/engines.md +++ b/docs/src/content/docs/reference/engines.md @@ -20,6 +20,26 @@ Set `engine:` in your workflow frontmatter and configure the corresponding secre Copilot CLI is the default — `engine:` can be omitted when using Copilot. See the linked authentication docs for secret setup instructions. +## Engine Feature Comparison + +Not all features are available across all engines. The table below summarizes per-engine support for commonly used workflow options: + +| Feature | Copilot | Claude | Codex | Gemini | +|---------|:-------:|:------:|:-----:|:------:| +| `max-turns` | ❌ | ✅ | ❌ | ❌ | +| `max-continuations` | ✅ | ❌ | ❌ | ❌ | +| `tools.web-fetch` | ✅ | ✅ | ✅ | ✅ | +| `tools.web-search` | via MCP | via MCP | ✅ (opt-in) | via MCP | +| `engine.agent` (custom agent file) | ✅ | ❌ | ❌ | ❌ | +| `engine.api-target` (custom endpoint) | ✅ | ✅ | ✅ | ✅ | +| Tools allowlist | ✅ | ✅ | ✅ | ✅ | + +**Notes:** +- `max-turns` limits the number of AI chat iterations per run (Claude only). +- `max-continuations` enables autopilot mode with multiple consecutive runs (Copilot only). +- `web-search` for Codex is disabled by default; add `tools: web-search:` to enable it. Other engines use a third-party MCP server — see [Using Web Search](/gh-aw/guides/web-search/). +- `engine.agent` references a `.github/agents/` file for custom Copilot agent behavior. See [Copilot Custom Configuration](#copilot-custom-configuration). + ## Extended Coding Agent Configuration Workflows can specify extended configuration for the coding agent: diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md index 26b4184c16c..a06155b6447 100644 --- a/docs/src/content/docs/reference/safe-outputs.md +++ b/docs/src/content/docs/reference/safe-outputs.md @@ -64,6 +64,7 @@ The agent requests issue creation; a separate job with `issues: write` creates i - [**Dispatch Workflow**](#workflow-dispatch-dispatch-workflow) (`dispatch-workflow`) - Trigger other workflows with inputs (max: 3, same-repo only) - [**Call Workflow**](#workflow-call-call-workflow) (`call-workflow`) - Call reusable workflows via compile-time fan-out (max: 1, same-repo only) +- [**Dispatch Repository Event**](#repository-dispatch-dispatch_repository) (`dispatch_repository`) - Trigger `repository_dispatch` events in external repositories, experimental (cross-repo) - [**Code Scanning Alerts**](#code-scanning-alerts-create-code-scanning-alert) (`create-code-scanning-alert`) - Generate SARIF security advisories (max: unlimited, same-repo only) - [**Autofix Code Scanning Alerts**](#autofix-code-scanning-alerts-autofix-code-scanning-alert) (`autofix-code-scanning-alert`) - Create automated fixes for code scanning alerts (max: 10, same-repo only) - [**Create Agent Session**](#agent-session-creation-create-agent-session) (`create-agent-session`) - Create Copilot coding agent sessions (max: 1) @@ -1269,6 +1270,55 @@ Use `call-workflow` for deterministic fan-out where actor attribution and zero A - **Allowlist enforcement** - Only workflows listed in `workflows` can be called; unlisted names are rejected at runtime. - **Compile-time validation** - Misconfiguration is caught before the workflow runs. +### Repository Dispatch (`dispatch_repository`) + +> [!CAUTION] +> This is an experimental feature. Compiling a workflow with `dispatch_repository` emits a warning: `Using experimental feature: dispatch_repository`. The API may change in future releases. + +Triggers [`repository_dispatch`](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#repository_dispatch) events in external repositories. Unlike `dispatch-workflow` (same-repo only), `dispatch_repository` is designed for cross-repository orchestration. + +Each key under `dispatch_repository:` defines a named tool exposed to the agent: + +```yaml wrap +safe-outputs: + dispatch_repository: + trigger_ci: + description: Trigger CI in another repository + workflow: ci.yml + event_type: ci_trigger + repository: ${{ inputs.target_repo }} # GitHub Actions expressions supported + inputs: + environment: + type: choice + options: [staging, production] + default: staging + max: 1 + notify_service: + workflow: notify.yml + event_type: notify_event + allowed_repositories: + - org/service-repo + - ${{ vars.DYNAMIC_REPO }} # Expressions bypass slug format validation + inputs: + message: + type: string +``` + +#### Configuration Fields (per tool) + +- **`workflow`** (required) — Identifier forwarded in `client_payload.workflow` so the receiving workflow can route by job type. +- **`event_type`** (required) — The `event_type` sent with the `repository_dispatch` event. +- **`repository`** (required, unless `allowed_repositories` is set) — Static `owner/repo` slug or a GitHub Actions expression (`${{ ... }}`). Expressions are passed through without format validation. +- **`allowed_repositories`** (required, unless `repository` is set) — List of allowed `owner/repo` slugs or expressions. The agent selects the target from this list at runtime. +- **`inputs`** (optional) — Structured input schema forwarded in `client_payload`. Supports `type: string`, `type: choice` (with `options`), and `default` values. +- **`description`** (optional) — Human-readable description of the tool shown to the agent. +- **`max`** (optional) — Maximum number of dispatches allowed per run (default: 1). + +#### Security + +- **Cross-repo allowlist** — At runtime the handler validates the target repository against the configured `repository` or `allowed_repositories` before calling the API (SEC-005). +- **Staged mode** — Supports `staged: true` for preview without dispatching. + ### Agent Session Creation (`create-agent-session:`) Creates Copilot coding agent sessions from workflow output. Allows workflows to spawn new agent sessions for follow-up work. diff --git a/docs/src/content/docs/troubleshooting/common-issues.md b/docs/src/content/docs/troubleshooting/common-issues.md index 2ed00c920e8..42574df4a45 100644 --- a/docs/src/content/docs/troubleshooting/common-issues.md +++ b/docs/src/content/docs/troubleshooting/common-issues.md @@ -85,6 +85,23 @@ The CLI validates three permission layers. Fix restrictions in Repository Settin ## Workflow Compilation Issues +### Frontmatter Field Not Taking Effect + +If a frontmatter setting appears to be silently ignored, the field name may be misspelled. The compiler does not warn about unknown field names — they are silently discarded. + +> [!WARNING] +> Common frontmatter field name mistakes: +> +> | Wrong | Correct | +> |-------|---------| +> | `agent:` | `engine:` | +> | `mcp-servers:` | `tools:` (under which MCP servers are configured) | +> | `tool-sets:` | `toolsets:` (under `tools.github:`) | +> | `allowed_repos:` | `allowed-repos:` (under `tools.github:`) | +> | `timeout:` | `timeout-minutes:` | +> +> Run `gh aw compile --verbose` to confirm which settings were parsed. If your setting is missing from the output, check the [Frontmatter Reference](/gh-aw/reference/frontmatter/) for the correct field name. + ### Workflow Won't Compile Check YAML frontmatter syntax (indentation, colons with spaces), verify required fields (`on:`), and ensure types match the schema. Use `gh aw compile --verbose` for details.