diff --git a/docs/src/content/docs/guides/upgrading.md b/docs/src/content/docs/guides/upgrading.md index 4bc954514ce..2c0e8e3ca56 100644 --- a/docs/src/content/docs/guides/upgrading.md +++ b/docs/src/content/docs/guides/upgrading.md @@ -77,14 +77,6 @@ The upgrade automatically applies codemods to fix deprecated fields in all workf | **delete-schema-file** | Deletes deprecated schema file | Removes `.github/aw/schemas/agentic-workflow.json` | | **delete-old-agents** | Deletes old `.agent.md` files moved to `.github/aw/` | Removes outdated agent files | -### 3.2.1 Manual Migrations (No Codemod) - -Some breaking changes require manual edits because no automatic codemod was shipped: - -| Change | What to do | -|--------|------------| -| `engine: id: opencode` removed (April 2026) | Change to `engine: id: crush`. The OpenCode engine was archived; Crush is its successor. Also update any `GH_AW_MODEL_AGENT_OPENCODE` org/repo variables to `GH_AW_MODEL_AGENT_CRUSH`. | - ### 3.3 Compiles All Workflows The upgrade automatically compiles all workflows to generate or update `.lock.yml` files, ensuring they're ready to run in GitHub Actions. diff --git a/docs/src/content/docs/reference/engines.md b/docs/src/content/docs/reference/engines.md index 2bca23b0bff..546923ac973 100644 --- a/docs/src/content/docs/reference/engines.md +++ b/docs/src/content/docs/reference/engines.md @@ -18,6 +18,7 @@ Set `engine:` in your workflow frontmatter and configure the corresponding secre | [OpenAI Codex](https://openai.com/blog/openai-codex) | `codex` | [OPENAI_API_KEY](/gh-aw/reference/auth/#openai_api_key) | | [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) | `gemini` | [GEMINI_API_KEY](/gh-aw/reference/auth/#gemini_api_key) | | [Crush](https://github.com/@charmland/crush/crush) (experimental) | `crush` | [COPILOT_GITHUB_TOKEN](/gh-aw/reference/auth/#copilot_github_token) | +| [OpenCode](https://opencode.ai) (experimental) | `opencode` | [COPILOT_GITHUB_TOKEN](/gh-aw/reference/auth/#copilot_github_token) | Copilot CLI is the default — `engine:` can be omitted when using Copilot. See the linked authentication docs for secret setup instructions. @@ -25,21 +26,23 @@ Copilot CLI is the default — `engine:` can be omitted when using Copilot. See 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 | Crush | -|---------|:-------:|:------:|:-----:|:------:|:--------:| -| `max-turns` | ❌ | ✅ | ❌ | ❌ | ❌ | -| `max-continuations` | ✅ | ❌ | ❌ | ❌ | ❌ | -| `tools.web-fetch` | ✅ | ✅ | ✅ | ✅ | ✅ | -| `tools.web-search` | via MCP | via MCP | ✅ (opt-in) | via MCP | via MCP | -| `engine.agent` (custom agent file) | ✅ | ❌ | ❌ | ❌ | ❌ | -| `engine.api-target` (custom endpoint) | ✅ | ✅ | ✅ | ✅ | ✅ | -| Tools allowlist | ✅ | ✅ | ✅ | ✅ | ❌ | +| Feature | Copilot | Claude | Codex | Gemini | Crush | OpenCode | +|---------|:-------:|:------:|:-----:|:------:|:-----:|:--------:| +| `max-turns` | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | +| `max-continuations` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | +| `tools.web-fetch` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| `tools.web-search` | via MCP | via MCP | ✅ (opt-in) | via MCP | via MCP | via MCP | +| `engine.agent` (custom agent file) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | +| `engine.api-target` (custom endpoint) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| `engine.driver` (custom driver script) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | +| 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). +- `engine.driver` allows replacing the built-in Copilot driver script. See [Custom Driver Script](#custom-driver-script-driver) below. ## Extended Coding Agent Configuration @@ -67,6 +70,7 @@ By default, workflows install the latest available version of each engine CLI. T | Codex | `codex` | `"0.111.0"` | | Gemini CLI | `gemini` | `"0.31.0"` | | Crush | `crush` | `"1.2.14"` | +| OpenCode | `opencode` | `"0.1.0"` | ```yaml wrap engine: @@ -206,6 +210,30 @@ engine: args: ["--verbose"] ``` +### Custom Driver Script (`driver`) + +The `driver` field lets you replace the built-in Node.js driver wrapper that the Copilot engine uses to launch the CLI. Use this when you need to customise startup behaviour, inject pre/post hooks, or test an alternative driver implementation. + +```yaml wrap +engine: + id: copilot + driver: custom_copilot_driver.cjs +``` + +The value must be a bare filename — no directory separators, no `..`, and no shell metacharacters. It must end with `.js`, `.cjs`, or `.mjs`. When `driver` is set, AWF automatically ensures Node 24 is available in the runner environment. + +> [!NOTE] +> `engine.driver` is currently only applied during Copilot engine execution. Setting it on other engines has no effect. + +**Validation rules:** + +| Rule | Valid example | Invalid example | +|------|--------------|-----------------| +| Bare filename only | `my_driver.cjs` | `subdir/driver.cjs` | +| No path traversal | `driver.mjs` | `../driver.cjs` | +| Must start with `[A-Za-z0-9_]` | `driver.js` | `-driver.cjs` | +| Must end with `.js`, `.cjs`, or `.mjs` | `wrapper.cjs` | `driver.sh` | + ### Custom Token Weights (`token-weights`) Override the built-in token cost multipliers used when computing [Effective Tokens](/gh-aw/reference/effective-tokens-specification/). Useful when your workflow uses a custom model not in the built-in list, or when you want to adjust the relative cost ratios for your use case. @@ -299,13 +327,13 @@ timeout-minutes: 60 ### Summary Table -| Timeout knob | Copilot | Claude | Codex | Gemini | Crush | Notes | -|---|:---:|:---:|:---:|:---:|:---:|---| -| `timeout-minutes` | ✅ | ✅ | ✅ | ✅ | ✅ | Job-level wall clock | -| `tools.timeout` | ✅ | ✅ | ✅ | ✅ | ✅ | Per tool-call limit (seconds) | -| `tools.startup-timeout` | ✅ | ✅ | ✅ | ✅ | ✅ | MCP server startup limit | -| `max-turns` | ❌ | ✅ | ❌ | ❌ | ❌ | Iteration budget (Claude only) | -| `max-continuations` | ✅ | ❌ | ❌ | ❌ | ❌ | Autopilot run budget (Copilot only) | +| Timeout knob | Copilot | Claude | Codex | Gemini | Crush | OpenCode | Notes | +|---|:---:|:---:|:---:|:---:|:---:|:---:|---| +| `timeout-minutes` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | Job-level wall clock | +| `tools.timeout` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | Per tool-call limit (seconds) | +| `tools.startup-timeout` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | MCP server startup limit | +| `max-turns` | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | Iteration budget (Claude only) | +| `max-continuations` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | Autopilot run budget (Copilot only) | ## Related Documentation diff --git a/docs/src/content/docs/reference/network.md b/docs/src/content/docs/reference/network.md index b15727fd154..4b7a7e3a67f 100644 --- a/docs/src/content/docs/reference/network.md +++ b/docs/src/content/docs/reference/network.md @@ -108,6 +108,30 @@ Mix ecosystem identifiers with specific domains for fine-grained control: Common identifiers: `python` (PyPI/pip), `node` (npm/yarn/pnpm), `containers` (Docker Hub/GHCR), `go` (proxy.golang.org). See the [Network Configuration Guide](/gh-aw/guides/network-configuration/) for complete domain lists, or the [Supported Languages](/gh-aw/reference/supported-languages/) page for a language-first overview. +### Ecosystem Identifier Validation + +Single-word entries in `network.allowed` that match the ecosystem identifier pattern (`[a-z][a-z0-9-]*`) are validated against the known ecosystem list at compile time. An unrecognised identifier produces a compilation error with the full list of valid options: + +```yaml wrap +# ❌ Compilation error: 'rustxxxx' is not a valid ecosystem identifier +network: + allowed: + - defaults + - rustxxxx + +# ✅ Use the correct identifier +network: + allowed: + - defaults + - rust + +# ✅ Dotted domain names are validated as domains, not ecosystem identifiers +network: + allowed: + - defaults + - crates.io +``` + ## Strict Mode Validation When [strict mode](/gh-aw/reference/frontmatter/#strict-mode-strict) is enabled (default), network configuration is validated to ensure security best practices. Strict mode recommends using ecosystem identifiers instead of individual domains for better maintainability.