From 6ced272432bcb5988e86c43a24d995920db1da9e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 14 Jul 2026 22:07:49 +0000 Subject: [PATCH 1/2] docs: add how-to guide for configuring a third-party agent (Gentek example) Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/astro.config.mjs | 1 + .../content/docs/guides/third-party-agent.md | 135 ++++++++++++++++++ 2 files changed, 136 insertions(+) create mode 100644 docs/src/content/docs/guides/third-party-agent.md 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..86add9b646b --- /dev/null +++ b/docs/src/content/docs/guides/third-party-agent.md @@ -0,0 +1,135 @@ +--- +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 [Gentek](https://github.com/gentekai/gentek) 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: Gentek + +Gentek publishes the following engine definition file at +`.github/workflows/gentek-engine.md` in their open-source repository: + +```aw wrap title=".github/workflows/gentek-engine.md (published by the Gentek project)" +--- +engine: + id: gentek + display-name: Gentek CLI + description: Gentek CLI with headless mode and multi-provider LLM support + runtime-id: crush + experimental: true + provider: + name: openai + auth: + secret: GENTEK_API_KEY + behaviors: + secret-strategy: universal-llm-consumer + capabilities: + max-turns: true + manifest: + files: + - gentek.json + - AGENTS.md + path-prefixes: + - .gentek/ + installation: + package-manager: npm + package-name: "@gentekai/gentek" + version: "1.0.0" + step-name: Install Gentek CLI + binary-name: gentek + include-node-setup: true + cooldown: true + verify-command: gentek --version + verify-step-name: Verify Gentek CLI installation + docs-url: https://github.com/gentekai/gentek + config-file: + path: gentek.json + step-name: Write Gentek Config + content: |- + { + "permission": { + "edit": "allow", + "bash": "allow", + "external_directory": "allow" + } + } + merge-strategy: json-merge + execution: + command-name: gentek + args: + - run + - --headless + step-name: Execute Gentek CLI + model-env-var: GENTEK_MODEL + mcp-config-env-var: GH_AW_MCP_CONFIG + write-timestamp: true + provider-env-mode: universal-llm-consumer + mcp: + config-path: gentek.json +--- +``` + +## Configure a workflow to use Gentek + +Import the engine definition file and set `engine: gentek` in your workflow: + +```aw wrap +on: issues + +engine: gentek + +imports: + - gentekai/gentek/.github/workflows/gentek-engine.md@v1.0.0 + +network: + allowed: + - defaults + - api.openai.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. + +## Add the API key secret + +Gentek reads its API key from `GENTEK_API_KEY`. Add the secret to your repository or organization: + +1. Go to **Settings → Secrets and variables → Actions**. +2. Create a new secret named `GENTEK_API_KEY` with the value from your Gentek account. + +## 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: gentek + version: "1.2.0" + +imports: + - gentekai/gentek/.github/workflows/gentek-engine.md@v1.0.0 +``` + +## 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 From b623e1af3355a74b67463174f3cd90224d273a7c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 14 Jul 2026 22:20:18 +0000 Subject: [PATCH 2/2] docs: use opencode as example in third-party agent guide Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .../content/docs/guides/third-party-agent.md | 101 ++++++++++-------- 1 file changed, 57 insertions(+), 44 deletions(-) diff --git a/docs/src/content/docs/guides/third-party-agent.md b/docs/src/content/docs/guides/third-party-agent.md index 86add9b646b..c57cbc99953 100644 --- a/docs/src/content/docs/guides/third-party-agent.md +++ b/docs/src/content/docs/guides/third-party-agent.md @@ -5,93 +5,102 @@ 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 [Gentek](https://github.com/gentekai/gentek) as a concrete open-source example. +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: Gentek +## Example: OpenCode -Gentek publishes the following engine definition file at -`.github/workflows/gentek-engine.md` in their open-source repository: +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. -```aw wrap title=".github/workflows/gentek-engine.md (published by the Gentek project)" +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: gentek - display-name: Gentek CLI - description: Gentek CLI with headless mode and multi-provider LLM support - runtime-id: crush + id: opencode + display-name: OpenCode + description: OpenCode CLI with headless mode and multi-provider LLM support + runtime-id: opencode experimental: true - provider: - name: openai - auth: - secret: GENTEK_API_KEY behaviors: secret-strategy: universal-llm-consumer capabilities: max-turns: true manifest: files: - - gentek.json + - opencode.jsonc - AGENTS.md path-prefixes: - - .gentek/ + - .opencode/ installation: package-manager: npm - package-name: "@gentekai/gentek" - version: "1.0.0" - step-name: Install Gentek CLI - binary-name: gentek + package-name: opencode-ai + version: "1.2.14" + step-name: Install OpenCode + binary-name: opencode include-node-setup: true cooldown: true - verify-command: gentek --version - verify-step-name: Verify Gentek CLI installation - docs-url: https://github.com/gentekai/gentek + verify-command: opencode --version + verify-step-name: Verify OpenCode CLI installation + docs-url: https://opencode.ai/docs config-file: - path: gentek.json - step-name: Write Gentek Config + path: opencode.jsonc + step-name: Write OpenCode Config content: |- { - "permission": { - "edit": "allow", - "bash": "allow", - "external_directory": "allow" - } + "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: gentek + command-name: opencode args: - run - - --headless - step-name: Execute Gentek CLI - model-env-var: GENTEK_MODEL + - --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: gentek.json + config-path: opencode.jsonc --- ``` -## Configure a workflow to use Gentek +## Configure a workflow to use OpenCode -Import the engine definition file and set `engine: gentek` in your workflow: +Import the engine definition file and set `engine: opencode` in your workflow: ```aw wrap on: issues -engine: gentek +engine: opencode imports: - - gentekai/gentek/.github/workflows/gentek-engine.md@v1.0.0 + - sst/opencode/.github/workflows/opencode-engine.md@v1.2.14 network: allowed: - defaults - - api.openai.com + - api.anthropic.com --- @@ -100,12 +109,16 @@ 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 -Gentek reads its API key from `GENTEK_API_KEY`. Add the secret to your repository or organization: +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 `GENTEK_API_KEY` with the value from your Gentek account. +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 @@ -113,11 +126,11 @@ The engine definition above declares a default CLI version under `behaviors.inst ```aw wrap engine: - id: gentek - version: "1.2.0" + id: opencode + version: "1.3.0" imports: - - gentekai/gentek/.github/workflows/gentek-engine.md@v1.0.0 + - sst/opencode/.github/workflows/opencode-engine.md@v1.2.14 ``` ## Recompile after workflow edits