接入 GitLab

OpenCode 可以通过 GitLab CI/CD 或 GitLab Duo 接入 GitLab 工作流。它运行在你的 GitLab Runner 上，用评论或流水线触发任务。

官方教程提供了 CI 组件、GitLab Duo、认证变量和示例流程。这里重点讲：新手应该选哪条路径、第一次怎么验证、哪些配置容易出问题。

先理解它解决什么问题

GitLab 集成适合把 OpenCode 放进团队协作流程：

在 issue 中解释问题、补充排查建议。
在 Merge Request 中审查改动。
为小范围问题创建分支和 MR。
在 CI/CD 中按固定 prompt 执行检查。

它的本质是“在 Runner 上运行的 AI 协作步骤”。因此你要先理解 Runner 权限、变量、仓库写权限，再让它改代码。

两条接入路径

GitLab 主要有两种接入方式：

GitLab CI 组件：适合先从普通流水线接入，配置更直接。
GitLab Duo：适合已经使用 Duo Agent Platform，希望通过 @opencode 评论触发。

新手建议先看 CI 组件。Duo 路径牵涉 GitLab 侧 Agent Platform、服务账户和更完整的组织配置，适合团队环境再上。

GitLab CI 组件怎么理解

CI 组件的思路是：你在 .gitlab-ci.yml 里引用 OpenCode 组件，并把认证 JSON 和初始 prompt 传进去。

最小结构是：

include:
  - component: $CI_SERVER_FQDN/nagyv/gitlab-opencode/opencode@2
    inputs:
      auth_json: $OPENCODE_AUTH_JSON
      message: "Explain this issue and suggest the next step"

这里最关键的是 `OPENCODE_AUTH_JSON`。它应该作为 GitLab CI/CD 的 File 类型变量保存，并标记为 masked / hidden。不要把认证 JSON 写进仓库。

第一次怎么试

第一次不要让它自动提交代码。先做只读验证：

创建测试 issue 或测试 MR。
用 CI 组件传入一个只读 prompt。
确认 Runner 能安装依赖、读取上下文、输出结果。
再逐步给写权限或 MR 创建能力。

推荐第一条 prompt：

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

先确认“能理解”，再确认“能修改”。

GitLab Duo 适合什么场景

如果你希望在 GitLab 评论里提及 @opencode 触发任务，可以走 GitLab Duo 路径。

适合：

团队已经使用 GitLab Duo / Agent Platform。
有稳定 Runner 和服务账户。
希望在 issue / MR 评论里直接指派 OpenCode。

不适合：

只是个人仓库想快速试用。
还没配置好 GitLab CI 变量和服务账户。
不清楚 Runner 会拿到哪些权限。

Duo 的具体平台配置建议直接跟随 GitLab 官方文档，因为这部分会随 GitLab 平台能力更新。

怎么写评论

评论要给出明确边界：

@opencode explain this issue

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

@opencode fix this small typo and open a merge request

不要只写 `@opencode fix`。GitLab 里的上下文可能很长，边界越清楚，输出越稳定。

权限和变量

GitLab 集成最容易出问题的是变量和权限：

模型 API Key 放 CI/CD Variables。
GitLab Token 或服务账户 Token 只给必要 scope。
能读 issue / MR 不等于能 push 分支。
Runner 所在环境能访问外网和模型 API。
CI 日志不要输出认证 JSON 或 API Key。

如果 OpenCode 需要创建 MR，就必须有对应仓库写权限；如果只做解释和审查，先不要给写权限。

怎么判断接入成功

成功标准：

Pipeline 能被正确触发。
Runner 能安装并运行 OpenCode。
OpenCode 能读取 GitLab 上下文。
只读任务不会意外提交代码。
写入任务能创建分支或 MR，并且提交者身份符合预期。

如果失败，先看 CI 日志里的三类问题：变量不存在、Token 权限不足、Runner 无法访问模型服务。

新手常见坑

把认证 JSON 当普通变量，而不是 File 类型变量。
在日志里 echo 密钥或 auth.json。
一开始就让它 push 代码，导致权限和安全问题一起出现。
没有区分 issue 解释、MR review、自动修复三类任务。
忽略 Runner 环境：本地能跑，不代表 CI Runner 能访问同样的网络和工具。

最近更新： 2026年5月1日

On this page