接入 GitHub

OpenCode 的 GitHub 集成让你在 Issue 或 Pull Request 评论里提及 /opencode 或 /oc，然后由 GitHub Actions runner 执行任务。它适合把本地 AI 编程会话接进团队协作流程，但不能替代代码审查和权限治理。

先给结论：先评论触发，再自动化

不要第一天就打开所有 GitHub 事件。推荐路径是：

flowchart LR
    Install["opencode github install"] --> Comment["评论触发 /opencode 或 /oc"]
    Comment --> ReadOnly["只读解释 Issue / PR"]
    ReadOnly --> SmallFix["小范围修复并开 PR"]
    SmallFix --> Review["人工 review / CI"]
    Review --> Auto["再考虑 PR review / schedule 自动化"]

    style Comment fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style ReadOnly fill:#dcfce7,stroke:#22c55e
    style Auto fill:#fee2e2,stroke:#ef4444

GitHub 集成最适合当“异步助手”：先处理边界清楚的小任务，再让人确认。不要把它当成自动合并机器人。

1. 它能做什么

官方文档列出的核心能力可以这样理解：

• Triage issues：读取 issue 上下文，解释问题，补充排查方向。
• Fix and implement：在新分支里修复问题或实现小功能，并提交 PR。
• Secure execution：OpenCode 运行在你的 GitHub runner 里。
• PR line context：在 “Files changed” 里评论具体代码行时，OpenCode 能拿到文件、行号和 diff 上下文。

适合接入的仓库通常已经有测试、lint、review 习惯，并且任务能通过分支和 PR 回收。不适合一开始就接生产密钥、后台权限、大规模重构或没有任何 CI 的仓库。

2. 最简单安装路径

在目标 GitHub 仓库本地运行：

opencode github install

它会引导你完成三件事：

1. 安装 OpenCode GitHub App。
2. 创建 GitHub Actions workflow。
3. 配置模型 API key 所需的 GitHub Actions Secrets。

新手优先走安装命令，不要手写整份 workflow。手写 workflow 适合你已经理解 GitHub Actions 权限、事件和 secrets 之后再做。

3. 手动接入要理解四件事

如果必须手动配置，先确认：

最小触发通常从评论事件开始：

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

再用条件限制触发词：

if: contains(github.event.comment.body, '/oc') || contains(github.event.comment.body, '/opencode')

4. 权限和 token 怎么理解

官方 workflow 起点至少会用到 id-token: write。如果希望 OpenCode 创建评论、提交、开分支或开 PR，还需要相应 GitHub 权限，例如：

permissions:
  id-token: write
  contents: write
  pull-requests: write
  issues: write

token 是可选项。默认情况下，OpenCode 可以使用 OpenCode GitHub App 的 installation access token；也可以使用 GitHub Action runner 内置的 GITHUB_TOKEN，或在特殊场景使用 PAT（Personal Access Token，个人访问令牌——绑在某个 GitHub 用户身上的长期 token，权限和那个用户完全相同）。

5. 关键配置项

公开仓库尤其要看 share。如果仓库或 issue 里可能出现内部路径、客户信息、私有服务地址或未公开策略，先关闭分享或不要在该仓库启用自动化。

6. 支持哪些事件

自动事件越多，噪音和误触发越多。先让评论触发跑稳，再考虑 PR 自动审查；最后才考虑 schedule。

7. 第一次怎么试

第一次验证用测试 issue，不要直接在重要 PR 上试。

只读验证：

/opencode explain this issue. Do not change files.

确认能读取 issue、理解上下文、回评论后，再试小范围修改：

/opencode fix the typo in the README and open a pull request.

PR 行评论里更推荐写清边界：

/oc review this change for regression risk. Do not modify files.

如果要让它修改代码，写清范围：

/oc add error handling for this branch only. Keep the public API unchanged.

8. 自动任务要写 prompt

issues、schedule、workflow_dispatch 这类事件没有自然语言评论上下文，必须写 prompt。比如 issue triage 可以只让它补文档链接、复现信息和下一步建议，不要默认修代码。

Schedule 任务还要注意：它没有用户上下文来做权限检查。如果希望它创建分支或 PR，workflow 必须显式授予 contents: write 和 pull-requests: write。

9. 安全验收

接入成功不只是 Action 变绿。至少检查：

• /opencode explain this issue 能触发 Actions。
• OpenCode 能读取 issue / PR 上下文。
• Secrets 只存在 Actions Secrets。
• 输出能回到 GitHub 评论或生成 PR。
• 权限不足时失败信息能看懂。
• 无关评论不会误触发。
• 公开仓库的 share、日志和评论不泄露敏感信息。

接下来去哪

官方资料

• OpenCode GitHub Integration：https://opencode.ai/docs/github
• OpenCode Permissions：https://opencode.ai/docs/permissions
• OpenCode Share：https://opencode.ai/docs/share
• GitHub Actions token：https://docs.github.com/en/actions/tutorials/authenticate-with-github_token