接入 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/