接入 GitHub

OpenCode 的 GitHub 集成让你可以在 Issue 或 Pull Request 评论里提及 /opencode 或 /oc，然后让 OpenCode 在 GitHub Actions Runner 中执行任务。

官方教程给出了安装命令、GitHub App、Actions 工作流、事件类型和配置项。这里按新手视角讲：什么场景值得接入、第一次怎么安全试跑、哪些权限不能随便放开。

先理解它解决什么问题

GitHub 集成解决的是“把 AI 编程从本地会话搬到协作流程里”的问题：

• Issue 里有人报错，可以让 OpenCode 先读上下文并解释。
• PR 里有人指出一行代码问题，可以让 OpenCode 基于 diff 提建议。
• 小范围 bug 或文档问题，可以让 OpenCode 创建分支并提交 PR。
• 定时任务可以周期性检查待办项、文档、依赖或维护项。

它不是替代代码审查，也不是让模型自动合并代码。它更适合做“异步助手”：先处理清楚边界的小任务，再由人确认。

什么时候适合接入

适合：

• 仓库已有测试、lint 或 review 习惯。
• Issue 和 PR 描述相对清楚。
• 任务可以通过分支和 PR 回收。
• 团队愿意把 AI 输出当成候选改动，而不是最终结论。

不适合：

• 仓库没有任何自动测试。
• 任务经常依赖生产密钥或后台权限。
• 一上来就想让它做大规模重构。
• 你还没有想清楚 GitHub Actions 权限边界。

最简单安装路径

在目标仓库本地运行：

opencode github install

它会引导你完成三件事：

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

新手优先走这个安装命令，不要一开始手写整份 workflow。手写配置适合你已经理解 GitHub Actions 权限和事件模型之后再做。

手动接入时要理解的四件事

如果你必须手动配置，先理解这四个点：

• 触发方式：常见是评论里写 /opencode 或 /oc。
• 运行位置：OpenCode 运行在你的 GitHub Actions Runner，不是在 OpenCode 官方服务器里直接改代码。
• 模型凭据：API Key 放在 GitHub Actions Secrets，不写进仓库。
• GitHub 权限：要评论、提交、开 PR，就必须给 workflow 对应权限。

最小权限通常从 id-token: write 开始；如果要创建分支或 PR，还需要 contents: write、pull-requests: write、issues: write。不要为了省事默认给所有权限。

第一次怎么试

第一次不要让它直接修复杂 bug。建议先用只读任务测试：

/opencode explain this issue

看它能否正确读取 Issue、理解上下文、给出清楚解释。确认没问题后，再试小范围任务：

/opencode fix the typo in the README

这个顺序能帮你验证安装、权限、模型凭据和 PR 创建链路，而不会一开始就冒大风险。

PR 里怎么提需求

在 PR 里不要只写“fix this”。更好的写法是给出边界：

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

或：

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

如果你在 “Files changed” 里对具体代码行评论，OpenCode 会拿到文件、行号和 diff 上下文。新手可以优先用这种方式，因为任务边界更明确。

自动事件要更谨慎

官方支持 issue_comment、pull_request_review_comment、issues、pull_request、schedule、workflow_dispatch 等事件。

新手建议顺序：

1. 先用评论触发：你明确写 /opencode 才运行。
2. 再考虑 PR 自动审查：每次 PR 更新时自动给建议。
3. 最后才考虑定时任务：它没有评论上下文，必须写清楚 prompt。

自动事件越多，噪音和误触发越多。先把一个流程跑稳，再扩展。

安全边界

接 GitHub 集成时，重点检查：

• Secrets 是否只存在 GitHub Actions Secrets。
• workflow 是否只给必要权限。
• 是否限制触发词，避免任何评论都触发。
• 公开仓库是否允许分享会话。
• 模型能否访问敏感文件或生成包含密钥的日志。

如果仓库是公开的，尤其要注意日志、会话分享和 PR 评论内容。不要把内部凭据、私有服务地址或客户数据暴露给 workflow 输出。

怎么判断接入成功

成功接入不只是 Action 变绿，还要看这几件事：

• 评论 /opencode explain this issue 后，Actions 能被触发。
• OpenCode 能读取 Issue 或 PR 上下文。
• 输出能回到 GitHub 评论或生成 PR。
• 权限不足时，失败信息能看懂，而不是静默失败。
• 不会在无关评论下误触发。

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

新手常见坑

• 一开始就让它修复杂问题，结果无法判断是模型问题、权限问题还是 workflow 问题。
• 把 API Key 写进 workflow 文件，而不是 GitHub Actions Secrets。
• 给了过大的 contents、pull-requests、issues 权限。
• 在公开仓库里忽略会话分享和日志输出。
• 没有限制触发词，导致无关评论也可能触发自动化。

© Anomaly

最近更新： 2026年5月1日