---
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="/docs/opencode/official/06-integrations/github" />
  <Card title="安全与团队使用" description="CI 变量、runner、日志和分享边界都属于团队安全基线。" href="/docs/opencode/understanding/08-security-share-team" />
  <Card title="权限配置" description="进入写入型任务前，先把 OpenCode 自身 permission 收紧。" href="/docs/opencode/official/05-security/permissions" />
  <Card title="网络配置" description="Runner 访问模型 API 失败时，从代理、NO_PROXY 和证书开始排查。" href="/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/)
