Skip to content

Repository navigation

opencode.mdx

Latest commit

 

History

History
107 lines (72 loc) · 5.04 KB

opencode.mdx

File metadata and controls

107 lines (72 loc) · 5.04 KB
Raw
title OpenCode runtime
description Configure OpenCode as the headless CLI runtime for Copilot AI features.

OpenCode integration

Source checkout only: this repository-maintainer script is not included in the installed CLI package. For a consumer installation, use copilot doctor --read-only, the installed CLI-provisioning workflow, and the first workflow to inspect metadata and verify actual execution.

Copilot invokes OpenCode as an external, headless CLI. The Action does not start an OpenCode HTTP server, manage a server URL, embed the OpenCode SDK, or choose an implicit model.

Recommended configuration

with:
  agent-provider: opencode
  agent-model-provider: openai
  agent-model: gpt-6-luna
  agent-effort: high
env:
  AGENT_ALLOWED_MODEL_PROVIDERS: openai
  AGENT_ALLOWED_MODELS: openai/gpt-6-luna
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Copilot constructs the qualified model reference openai/gpt-6-luna; its managed policy owns this argv shape:

opencode run --pure --agent copilot-controlled-readonly --format json \
  --model openai/gpt-6-luna --variant high

The runtime (opencode), model provider (openai), model (gpt-6-luna), credential, and allowlist are separate concerns. See Agent CLI configuration for the complete contract.

Credentials

For CI, provide the selected model provider's credential through a GitHub Secret mapped only onto the Copilot action step. For OpenAI, use OPENAI_API_KEY.

Do not put API keys in action inputs, command arguments, prompts, repository files, or logs. A local OAuth login may work on a controlled self-hosted runner, but local authentication files must not be copied into GitHub-hosted CI.

OpenCode supports many providers and local models. That flexibility does not change the Copilot agent contract: the effective provider/model must be explicitly selected and, when configured, must pass the allowlists before the CLI starts.

Runtime and provisioning

The Action reuses an available opencode executable. If the default command is missing, it uses the official standalone installer on Unix or the official release archive on Windows. The installation is private to the job and uses no npm or pnpm. Any non-empty version is accepted subject to the normal guarded preflight; the reviewed 1.18.3 identity is a historical smoke baseline.

opencode --version
opencode run --help

See Agent CLI provisioning and Agent CLI runners.

OpenCode behavior controlled by Copilot

  • The reviewed known-good smoke baseline is 1.18.3; other versions must pass the same fixed command contract.
  • --pure, the managed role, JSON event output, model, and optional --variant are reconstructed by policy.
  • The isolated config has wildcard default deny. It allows read/glob/grep/list, allows edit only for fixer, and denies bash, LSP, web, tasks, skills, questions, external directories, plugins, MCP, subagent depth, and session sharing.
  • The config directory and contents are ephemeral and hashed; repository OpenCode configuration is rejected.
  • No interactive TUI login or arbitrary CLI arguments are available during a headless run.
  • A provider failure is terminal; Copilot does not fall back to another provider or model.
  • Repository-local OpenCode defaults cannot silently replace the selected qualified model.

Local smoke test

Only run a real provider request when the user has authorized the provider, credential, and cost. A harmless test for the recommended configuration is:

timeout 120s opencode run --pure --model openai/gpt-6-luna \
  'Reply with exactly READY. Do not inspect or modify files.'

The expected evidence is READY and exit code 0. A successful binary/help check alone is not evidence that the selected provider is authenticated.

Troubleshooting

Missing executable

Check the official installer or provide a compatible CLI on the runner, then rerun:

command -v opencode
opencode --version
node scripts/verify-agent-clis.cjs

Missing credential

Check that the required GitHub Secret is mapped to the runner environment. Never print the value while diagnosing it.

Provider or model rejected

Check the three agent-* values and the two allowlists. The qualified model must match an exact allowed value, for example openai/gpt-6-luna.

Configuration appears to be ignored

Remove repository opencode.json, opencode.jsonc, or .opencode configuration from the managed workspace. Copilot intentionally rejects ambient provider configuration rather than merging it with its policy.

Related pages