接入 GitLab

你是 OpenCode GitLab 整合顧問。

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

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

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

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

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

OpenCode 可以透過 GitLab CI/CD pipeline 或 GitLab Duo 接入 GitLab 工作流。兩條路徑的共同點是：OpenCode 執行在你的 GitLab Runner 上，憑據、網路、許可權和記錄都屬於你的 CI 環境邊界。

先給結論：先 CI 只讀，再 Duo 評論觸發

個人或小團隊先用 GitLab CI component 跑通只讀任務；已經使用 GitLab Duo / Agent Platform 的組織，再考慮 @opencode 評論觸發。

flowchart LR
    CI["GitLab CI component"] --> ReadOnly["只讀 prompt"]
    ReadOnly --> Runner["驗證 Runner / 變數 / 網路"]
    Runner --> Write["小範圍寫入"]
    Write --> MR["建立 MR"]
    Duo["GitLab Duo"] --> Mention["@opencode 評論觸發"]
    Mention --> Runner

    style ReadOnly fill:#dcfce7,stroke:#22c55e
    style Runner fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style Write fill:#fef3c7,stroke:#f59e0b
    style MR fill:#fee2e2,stroke:#ef4444

GitLab 整合不是“讓模型自動接管儲存庫”，而是在 Runner 上增加一個 AI 協作步驟。Runner 有什麼許可權，OpenCode 就可能觸碰什麼邊界。

1. 兩條路徑怎麼選

新手優先 CI component。Duo 路徑牽涉 GitLab 平臺能力、服務賬戶和 flow 設定，適合團隊環境再做。

2. GitLab CI component

官方頁使用社群 CI/CD component：nagyv/gitlab-opencode。它的作用是幫你在 pipeline 中設定 OpenCode，你主要提供設定目錄、認證 JSON、可選 command 和初始 prompt。

最小結構：

include:
  - component: $CI_SERVER_FQDN/nagyv/gitlab-opencode/opencode@2
    inputs:
      config_dir: ${CI_PROJECT_DIR}/opencode-config
      auth_json: $OPENCODE_AUTH_JSON
      command: optional-custom-command
      message: "Explain this issue and suggest the next step"

OPENCODE_AUTH_JSON 應該儲存為 GitLab CI/CD 的 File 型別變數，並標記為 masked / hidden。不要把 auth JSON、API key 或 token 寫進儲存庫。

3. 第一次怎麼試

第一次只讀，不提交程式碼：

Read the current issue or merge request context.
Summarize the problem and list the safest next action.
Do not change files.

驗收順序：

1. Pipeline 能觸發。
2. Runner 能安裝並執行 OpenCode。
3. OPENCODE_AUTH_JSON 能被讀取。
4. 模型 provider 可訪問。
5. 輸出能回到 CI 記錄或預期位置。
6. 沒有產生 git diff、branch、commit 或 MR。

只讀任務穩定後，再試 typo、README、測試說明這類低風險寫入。

4. GitLab Duo 路徑

GitLab Duo 路徑適合在 Issue 或 Merge Request 評論裡提及 @opencode 觸發任務。官方文件提醒要跟隨 GitLab Duo Agent Platform 的最新設定。

通常需要：

• 設定 GitLab 環境和 CI/CD。
• 獲取 AI model provider API key。
• 建立服務賬戶。
• 設定 CI/CD variables。
• 建立 flow config。
• 在 flow 中安裝 OpenCode 和 glab，並讓 OpenCode 使用 GitLab 上下文。

這條路徑的價值是評論互動更自然；成本是平臺設定更重。組織沒有穩定 Runner、服務賬戶和變數治理前，不建議先走 Duo。

5. 評論怎麼寫

可以設定不同觸發詞；官方示例使用 @opencode。

只讀解釋：

@opencode explain this issue

MR 審查：

@opencode review this merge request. Do not change files.

小範圍修復：

@opencode fix this small typo and open a merge request.

不要只寫 @opencode fix。GitLab issue / MR 上下文可能很長，邊界越明確，輸出越穩定。

6. 變數、Token 和 Runner 許可權

GitLab 整合最容易出問題的是變數和許可權：

• 模型 API key 放 CI/CD Variables。
• OpenCode auth JSON 放 File 型別變數。
• GitLab token 或服務賬戶 token 只給必要 scope。
• 能讀 issue / MR 不等於能 push 分支。
• Runner 必須能訪問模型 provider、GitLab API 和所需包源。
• CI 記錄不能輸出 auth JSON、API key 或 token。

如果 OpenCode 需要建立 MR，就必須有儲存庫寫許可權；如果只做解釋和審查，先不給寫許可權。

7. 成功標準

接入成功不只是 pipeline 變綠。至少檢查：

• Pipeline 或 Duo flow 能被正確觸發。
• OpenCode 能讀取 issue / MR 上下文。
• 只讀任務不會提交程式碼。
• 寫入任務能建立分支或 MR。
• 提交者身份符合團隊預期。
• 變數缺失、token 許可權不足、網路不可達時，失敗資訊能看懂。

8. 常見坑

• 把認證 JSON 當普通變數，而不是 File 型別變數。
• 在記錄裡 echo 金鑰或 auth JSON。
• 一開始就讓它 push 程式碼，導致許可權和安全問題一起出現。
• 沒區分 issue 解釋、MR review、自動修復三類任務。
• 忽略 Runner 環境差異。
• Duo flow 裡硬編碼專案 URL、token 或個人賬號。

接下來去哪

官方資料

• OpenCode GitLab Integration：https://opencode.ai/docs/gitlab
• GitLab CI/CD components：https://docs.gitlab.com/ee/ci/components/
• nagyv/gitlab-opencode component：https://gitlab.com/nagyv/gitlab-opencode
• GitLab Duo Agent Platform：https://docs.gitlab.com/user/duo_agent_platform/agent_assistant/