接入 GitLab

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/