---
title: "接入 GitLab"
description: "在 GitLab Issue、Merge Request 和 CI/CD 中使用 OpenCode。"
verifiedAt: "2026-05-09"
---

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

> [!NOTE]
> **這一篇用 12 分鐘換什麼**：你會知道 GitLab CI component 和 GitLab Duo 該怎麼選，`OPENCODE_AUTH_JSON` 為什麼要用 File 型別變數，第一次如何只讀試跑，以及什麼時候才允許 OpenCode 建立分支和 Merge Request。

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

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

```mermaid
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. 兩條路徑怎麼選

| 路徑 | 適合誰 | 關鍵前提 |
| --- | --- | --- |
| GitLab CI component | 想先在普通 pipeline 裡跑 OpenCode | 有 Runner、CI/CD Variables、明確 prompt |
| GitLab Duo | 已經使用 Duo Agent Platform，希望評論觸發 | 需要 GitLab Duo 側配置、服務賬戶、flow config |

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

## 2. GitLab CI component

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

最小結構：

```yaml title=".gitlab-ci.yml"
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 写进仓库。

> [!IMPORTANT]
> File 类型变量和普通变量不是一回事。认证 JSON 适合 File 类型变量，否则很容易在日志、echo 或调试输出里泄露。

## 3. 第一次怎么试

第一次只读，不提交代码：

```text
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`。

只读解释：

```text
@opencode explain this issue
```

MR 审查：

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

小范围修复：

```text
@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，就必須有儲存庫寫許可權；如果只做解釋和審查，先不給寫許可權。

> [!WARNING]
> 本地能跑不代表 GitLab Runner 能跑。Runner 的系統包、網路代理、證書、DNS、包管理器和 Git 憑據都可能不同。

## 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 或個人賬號。

## 接下來去哪

<Cards>
  <Card title="GitHub 整合" description="對比 GitHub Actions runner 和 GitLab Runner 的許可權模型。" href="/zh-Hant/docs/opencode/official/06-integrations/github" />
  <Card title="安全與團隊使用" description="CI 變數、runner、日誌和分享邊界都屬於團隊安全基線。" href="/zh-Hant/docs/opencode/understanding/08-security-share-team" />
  <Card title="許可權配置" description="進入寫入型任務前，先把 OpenCode 自身 permission 收緊。" href="/zh-Hant/docs/opencode/official/05-security/permissions" />
  <Card title="網路配置" description="Runner 訪問模型 API 失敗時，從代理、NO_PROXY 和證書開始排查。" href="/zh-Hant/docs/opencode/official/05-security/network" />
</Cards>

## 官方資料

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