diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 5d26112eae6..69867e5b6a0 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -319,6 +319,7 @@ export default defineConfig({ { label: 'Using MCPs', link: '/guides/mcps/' }, { label: 'Network Configuration', link: '/guides/network-configuration/' }, { label: 'Azure OpenAI BYOK', link: '/guides/azure-openai-byok/' }, + { label: 'Third-Party Agent', link: '/guides/third-party-agent/' }, { label: 'ARC DinD for Copilot Coding Agent', link: '/guides/arc-dind-copilot-agent/' }, { label: 'OpenTelemetry', link: '/guides/open-telemetry/' }, { label: 'GitHub Actions Primer', link: '/guides/github-actions-primer/' }, diff --git a/docs/src/content/docs/guides/third-party-agent.md b/docs/src/content/docs/guides/third-party-agent.md new file mode 100644 index 00000000000..c57cbc99953 --- /dev/null +++ b/docs/src/content/docs/guides/third-party-agent.md @@ -0,0 +1,148 @@ +--- +title: How to configure a third-party agent +description: Use a third-party coding agent with GitHub Agentic Workflows by importing an engine definition file distributed by the agent's publisher. +sidebar: + order: 330 +--- + +Third-party coding agent CLIs that are not built into gh-aw can integrate through a declarative engine definition file that the agent publisher distributes. This guide uses [OpenCode](https://opencode.ai) as a concrete open-source example. + +## How third-party engine integration works + +A third-party agent publishes a Markdown engine definition file to their GitHub repository. The file's frontmatter declares the agent's installation, configuration, and execution steps using the `engine.behaviors` format. When a workflow imports that file, gh-aw registers the engine at compile time — no changes to the gh-aw binary are required. + +## Example: OpenCode + +OpenCode is an open-source, provider-agnostic AI coding agent (BYOK — Bring Your Own Key) that supports 75+ models from Anthropic, OpenAI, Google, Groq, and others via a unified CLI interface. + +An agent publisher provides an engine definition file like the following in their repository. The file's `engine.behaviors` block tells gh-aw exactly how to install, configure, and invoke the CLI: + +```aw wrap title=".github/workflows/opencode-engine.md (published by the OpenCode project)" +--- +engine: + id: opencode + display-name: OpenCode + description: OpenCode CLI with headless mode and multi-provider LLM support + runtime-id: opencode + experimental: true + behaviors: + secret-strategy: universal-llm-consumer + capabilities: + max-turns: true + manifest: + files: + - opencode.jsonc + - AGENTS.md + path-prefixes: + - .opencode/ + installation: + package-manager: npm + package-name: opencode-ai + version: "1.2.14" + step-name: Install OpenCode + binary-name: opencode + include-node-setup: true + cooldown: true + verify-command: opencode --version + verify-step-name: Verify OpenCode CLI installation + docs-url: https://opencode.ai/docs + config-file: + path: opencode.jsonc + step-name: Write OpenCode Config + content: |- + { + "agent": { + "build": { + "permission": { + "bash": "allow", + "edit": "allow", + "read": "allow", + "glob": "allow", + "grep": "allow", + "webfetch": "allow", + "websearch": "allow", + "external_directory": "allow" + } + } + }, + "autoupdate": false + } + merge-strategy: json-merge + execution: + command-name: opencode + args: + - run + - --print-logs + - --log-level + - DEBUG + step-name: Execute OpenCode CLI + model-env-var: OPENCODE_MODEL + mcp-config-env-var: GH_AW_MCP_CONFIG + write-timestamp: true + provider-env-mode: universal-llm-consumer + mcp: + config-path: opencode.jsonc +--- +``` + +## Configure a workflow to use OpenCode + +Import the engine definition file and set `engine: opencode` in your workflow: + +```aw wrap +on: issues + +engine: opencode + +imports: + - sst/opencode/.github/workflows/opencode-engine.md@v1.2.14 + +network: + allowed: + - defaults + - api.anthropic.com + +--- + +Triage this issue and apply an appropriate label. +``` + +Pin the import to a specific tag or SHA to control when you pick up new versions of the engine definition. + +The `network.allowed` entry should match the provider you are using. OpenCode supports multiple providers — for example, add `api.openai.com` instead of (or in addition to) `api.anthropic.com` when using an OpenAI model. + +## Add the API key secret + +OpenCode reads provider credentials from environment variables. For the default Anthropic provider, add `ANTHROPIC_API_KEY` to your repository or organization: + +1. Go to **Settings → Secrets and variables → Actions**. +2. Create a new secret named `ANTHROPIC_API_KEY` with the value from your Anthropic account. + +For other providers, set the corresponding key (for example `OPENAI_API_KEY` for OpenAI models) and reference it in your workflow's `engine.env` block. + +## Pin the engine version + +The engine definition above declares a default CLI version under `behaviors.installation.version`. Override it with `engine.version` in your workflow to pin or upgrade independently of the engine definition file: + +```aw wrap +engine: + id: opencode + version: "1.3.0" + +imports: + - sst/opencode/.github/workflows/opencode-engine.md@v1.2.14 +``` + +## Recompile after workflow edits + +Engine settings live in workflow frontmatter. Recompile whenever you change the import reference, the engine version, or any other frontmatter field: + +```bash +gh aw compile .github/workflows/my-workflow.md --watch +``` + +## Related documentation + +- [AI Engines Reference](/gh-aw/reference/engines/) — built-in engine options and configuration +- [Imports Reference](/gh-aw/reference/imports/) — how imports and frontmatter merging work +- [Network Configuration Guide](/gh-aw/guides/network-configuration/) — configuring outbound network access