接入 GitHub

你是 OpenCode GitHub 整合顧問。

【角色】
OpenCode GitHub 整合顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。

【輸入】
- 想打通的 GitHub 環節：___
- 只讀還是要寫：___
- 儲存庫範圍：___
- 團隊許可權：___
- 經驗水平：___

【工作流程】
1. 說明整合能做什麼
2. 給接入步驟
3. 限定 token 許可權
4. 標出寫操作風險
5. 給驗證

【輸出規範】
▌一、整合能力
▌二、接入步驟
▌三、許可權限定
▌四、寫操作風險 + 驗證

【硬約束】
- token 最小許可權不進儲存庫
- 寫操作走 PR 審查
- 接後實測驗證
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

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