opencode-actions

中文文档

Reusable GitHub Actions for installing and running OpenCode in other repositories.

This repository is licensed under Apache 2.0.

TLDR

Write this in your CI.yaml

- name: Run OpenCode multi-review
  uses: sun-praise/opencode-actions/multi-review@v4
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    model: deepseek/deepseek-v4-flash
    default-team: "quality:1,security:1,performance:1"
    timeout-seconds: "900"

    # only one is enough.
    deepseek-api-key: ${{ secrets.DEEPSEEK_API_KEY }}
    zhipu-api-key: ${{ secrets.ZHIPU_API_KEY }}
    litellm-url: ${{ secrets.LITELLM_URL }}
    litellm-api-key: ${{ secrets.LITELLM_API_KEY }}

You'll get an automatic reviewer (Chinese by default, configurable via language input).

Or add the skills to your project:

npx skills add sun-praise/opencode-actions

What it includes

• multi-review: multi-agent parallel review using OpenCode SDK — multiple reviewers run concurrently, a coordinator synthesizes findings into one PR comment
• github-run-opencode: one-step wrapper for the common opencode github run workflow
• setup-opencode: installs OpenCode, restores a dedicated cache, and exports the binary path
• run-opencode: runs opencode with optional retry logic for flaky GitHub network failures

Current scope

• Linux only
• installer-based bootstrap via https://opencode.ai/install
• cache is best-effort and does not pin an exact OpenCode version
• by default setup-opencode ignores unrelated opencode binaries already present on PATH; set allow-preinstalled: true only if you explicitly trust the runner image

github-run-opencode

Use this when you want the shortest consumer workflow for opencode github run.

Common inputs

Input	Default	Description
model	MODEL_NAME, else zhipuai-coding-plan/glm-5.1	Exported as MODEL before opencode github run; explicit input still overrides
fallback-models	empty	Optional ordered fallback models, filtered by available provider API keys
model-timeout-seconds	300	Per-model timeout before rotating to the next fallback candidate when fallbacks are configured; 0 disables it
fallback-on-regex	timeout regex	Rotate to the next fallback candidate when output matches this regex
prompt	built-in PR review template	Exported as PROMPT before opencode github run
github-token	empty	Exported as GITHUB_TOKEN before opencode github run
zhipu-api-key	empty	Exported as ZHIPU_API_KEY before opencode github run
deepseek-api-key	empty	Exported as DEEPSEEK_API_KEY before opencode github run
opencode-go-api-key	empty	Exported as OPENCODE_GO_API_KEY before opencode github run
minimax-api-key	empty	Exported as MINIMAX_API_KEY before opencode github run
xiaomi-api-key	empty	Exported as XIAOMI_API_KEY before opencode github run
litellm-url	empty	Base URL for LiteLLM proxy endpoint
litellm-api-key	empty	API key for LiteLLM provider (exported as LITELLM_API_KEY)
reasoning-effort	max	Reasoning effort level for the model agent (low, medium, high, max)
enable-thinking	true	Enable thinking mode for the model agent
use-github-token	true	Exported as USE_GITHUB_TOKEN before opencode github run
language	zh	Response language: zh for Chinese, en for English
extra-env	empty	Extra environment variables (multi-line KEY=VALUE pairs)
extra-env-allow-sensitive	false	When false, blocks extra-env entries that override sensitive runtime variables (API keys, MODEL, etc.); set true to allow with warning
attempts	3	Total attempts before failing
retry-profile	github-network	Built-in retry preset for common GitHub failures
timeout-seconds	600	Maximum execution time for opencode github run; 0 disables it
working-directory	empty	Optional working directory before running OpenCode

github-run-opencode also accepts the setup-related inputs from setup-opencode, such as cache, cache-key, install-attempts, install-url, and allow-preinstalled.

multi-review

Use this when you want multiple AI reviewers to analyze a PR in parallel, with a coordinator that synthesizes all findings into a single comment.

• spawns N reviewer sessions in parallel via the OpenCode SDK (@opencode-ai/sdk)
• built-in reviewer personas: quality, security, performance, architecture, regression-test, feature-missing, test-value, spec-coverage
• a coordinator session reads all reviewer outputs and produces a deduplicated synthesis
• each reviewer's detailed output is included in a collapsible <details> section
• single opencode serve instance shared across all sessions (one MCP cold start)

- name: Run OpenCode multi-review
  uses: sun-praise/opencode-actions/multi-review@v4
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    model: deepseek/deepseek-v4-flash
    default-team: "quality:1,security:1,performance:1"
    timeout-seconds: "900"
    coordinator-timeout-seconds: "300"
    deepseek-api-key: ${{ secrets.DEEPSEEK_API_KEY }}
    litellm-url: ${{ secrets.LITELLM_URL }}
    litellm-api-key: ${{ secrets.LITELLM_API_KEY }}

Inputs

Input	Default	Description
model	empty	Model for all reviewers and coordinator (format: provider/model)
default-team	empty	Comma-separated team definition (e.g. "quality:1,security:1,performance:1")
timeout-seconds	900	Global timeout for all reviewers in seconds
coordinator-timeout-seconds	300	Timeout for the coordinator synthesis step
coordinator-prompt	empty	Custom coordinator prompt; use {{REVIEWS}} as placeholder
working-directory	empty	Optional working directory before running review
github-token	empty	GitHub token for posting PR comments
zhipu-api-key	empty	Zhipu AI API key
opencode-go-api-key	empty	OpenCode Go API key
minimax-api-key	empty	MiniMax API key (not compatible with multi-review due to concurrency limits)
deepseek-api-key	empty	DeepSeek API key (recommended for multi-review)
xiaomi-api-key	empty	Xiaomi MiMo API key (not compatible with multi-review due to concurrency limits)
litellm-url	empty	Base URL for LiteLLM proxy endpoint
litellm-api-key	empty	API key for LiteLLM provider (exported as LITELLM_API_KEY)
extra-env	empty	Extra environment variables (multi-line KEY=VALUE pairs)
extra-env-allow-sensitive	false	When false, blocks extra-env entries that override sensitive runtime variables; set true to allow with warning. The MULTI_REVIEW_ prefix is always blocked regardless of this setting
cleanup-error-comments	true	Auto-delete error comments after a failed run

multi-review also accepts all setup-related inputs from setup-opencode (install-url, install-dir, xdg-cache-home, cache, cache-key, install-attempts, allow-preinstalled, version).

setup-opencode

Inputs

Input	Default	Description
install-url	https://opencode.ai/install	Installer URL used to bootstrap OpenCode
install-dir	computed	Directory where opencode will be installed
xdg-cache-home	computed	Dedicated XDG cache directory
cache	false	Enable actions/cache for install and cache directories
cache-key	v1	Cache key suffix used to invalidate installer caches
install-attempts	3	Total installer attempts
allow-preinstalled	false	Reuse an existing trusted opencode already present on PATH

The internal cache key also includes a hash of install-url, so changing installer sources does not silently reuse an older cache entry.

Outputs

Output	Description
opencode-path	Resolved absolute path to opencode
install-dir	Resolved install directory
xdg-cache-home	Resolved XDG cache directory
cache-hit	Whether actions/cache restored a hit
version	opencode --version output

run-opencode

Inputs

Input	Default	Description
args	empty	Space-delimited arguments passed to opencode
working-directory	empty	Working directory used before invoking OpenCode
attempts	1	Total attempts before failing
retry-on-regex	empty	Retry only when command output matches this regex
retry-profile	empty	Built-in retry preset such as github-network
retry-delay-seconds	15	Base delay used between retries
opencode-path	opencode	Explicit binary path from setup-opencode
reasoning-effort	max	Reasoning effort level for the model agent (low, medium, high, max)
enable-thinking	true	Enable thinking mode for the model agent

run-opencode intentionally keeps provider secrets and model selection in workflow env: so the action stays generic. In the common same-job case, setup-opencode already exports opencode to PATH, so you do not need to pass opencode-path into run-opencode.

Usage

Public consumers should reference the subdirectory action path:

uses: sun-praise/opencode-actions/multi-review@v4
uses: sun-praise/opencode-actions/github-run-opencode@v4
uses: sun-praise/opencode-actions/setup-opencode@v4
uses: sun-praise/opencode-actions/run-opencode@v4

- name: Run OpenCode multi-review
  uses: sun-praise/opencode-actions/multi-review@v4
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    model: deepseek/deepseek-v4-flash
    default-team: "quality:1,security:1,performance:1"
    deepseek-api-key: ${{ secrets.DEEPSEEK_API_KEY }}

More examples live in examples/.

To use English output, set the language input:

- name: Run OpenCode multi-review (English)
  uses: sun-praise/opencode-actions/multi-review@v4
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    language: en

Or configure it from repository variables:

- name: Run OpenCode multi-review
  uses: sun-praise/opencode-actions/multi-review@v4
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    language: ${{ vars.OPENCODE_LANGUAGE }}

If you need more control, you can still use setup-opencode and run-opencode directly. For example, pass opencode-path explicitly when reusing a binary from another job or a custom location.

The PR review example intentionally skips forked pull requests because repository secrets are not exposed there by default. The comment-command example also skips forked pull requests for the same reason. The comment-command example only allows OWNER, MEMBER, and COLLABORATOR comments to trigger the workflow.

Local verification

bash tests/test.sh

CI

This repository includes a CI workflow that:

• runs shellcheck on every bundled shell script
• runs the local shell-based regression suite
• smoke-tests all actions through uses: ./setup-opencode, uses: ./run-opencode, uses: ./github-run-opencode, and uses: ./multi-review

Release Policy

• publish immutable releases as v1.0.0, v1.1.0, v1.1.1, and so on
• consumers can pin to @v1 for compatible updates
• security-sensitive consumers should pin to a full commit SHA instead of a moving major tag
• this repository updates the repo-wide major tag like v1 when a semver GitHub release is published

Publishing Checklist

1. Push the repository publicly.
2. Verify CI passes on main.
3. Create a GitHub release with a semver tag such as v1.0.0.
4. Confirm the Update Major Tag workflow moved v1 to that release.
5. Use owner/repo/multi-review@v4 for multi-agent parallel review, owner/repo/github-run-opencode@v4 for generic github run, or owner/repo/setup-opencode@v4 plus owner/repo/run-opencode@v4 for more control.

The initial release-notes template lives at docs/releases/v1.0.0.md.

Limitations

• args is parsed as a space-delimited string, so keep complex text in environment variables like PROMPT
• the installer is external, so cache invalidation uses cache-key instead of a guaranteed version pin
• first version is optimized for GitHub-hosted or Linux self-hosted runners