接入 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