GitLab + OpenCode AI 自动化工作流实战教程：配置CI/CD与Duo机器人

📚 分类: DevOps / AI 集成 ⏱️ 预计耗时: 45 分钟 🎯 难度: 中级 🔧 环境要求: GitLab 账号 (管理员或项目维护者权限)，一个已注册并激活的 GitLab Runner 🌐 原文来源: OpenCode 官方文档 (整合)

你将学到什么

完成本教程后，你将能够：

[ ] 掌握两种在 GitLab 中集成 OpenCode 的方法：流水线 (CI/CD) 与 Duo
[ ] 独立配置 GitLab CI/CD 组件，让 OpenCode 自动处理 Issue 和 Merge Request
[ ] 理解并配置 @opencode 机器人，实现“一句话”驱动代码开发
[ ] 搭建一个安全的、可复用的自动化 AI 代码审查与修复流水线

最终效果

在 GitLab 项目中，你将可以实现以下操作：

自动化 Issue 解释：在 Issue 下评论 @opencode explain this issue，AI 会自动分析并回复解释。
自动化 Bug 修复：在 Issue 下评论 @opencode fix this，AI 会自动创建一个新分支，提交修复代码，并创建一个 Merge Request。
自动化代码审查：在 Merge Request 下评论 @opencode review this merge request，AI 会自动审查代码并提供反馈。

这一切都在你自有的 GitLab Runner 上安全运行，无需将代码发送给第三方。

前置准备

在开始前，请确认你的环境满足以下条件：

检查项	要求	说明
GitLab 账号	项目 Maintainer 或更高权限	用于配置 CI/CD 变量和流水线
AI 模型 API Key	Anthropic (Claude) 或 OpenAI (GPT-4)	OpenCode 需要调用 AI 模型
GitLab Runner	已注册并激活	用于执行 CI/CD 任务

1. 获取 AI 模型 API Key

OpenCode 需要一个 AI 模型来理解你的指令。你需要从模型提供商处获取 API Key。

Anthropic (Claude): 访问 console.anthropic.com 申请 API Key。
OpenAI (GPT-4): 访问 platform.openai.com 申请 API Key。

💡 提示：本教程以 Anthropic 的 Claude 为例。如果你使用 OpenAI，只需在后续的配置文件中将 "anthropic" 替换为 "openai"，并修改相应的 API Key 变量名。

第 1 步：配置 GitLab CI/CD 变量

🎯 目标：将敏感信息 (API Key) 安全地存储在 GitLab 项目中，供后续流水线使用。

📝 操作：

打开你的 GitLab 项目。
进入 Settings > CI/CD > Variables。
展开该区域，点击 Add variable 按钮。
添加以下两个变量：

Key	Value	属性
`ANTHROPIC_API_KEY`	你的 Anthropic API Key	勾选 "Masked and hidden" (隐藏值)
`GITLAB_TOKEN_OPENCODE`	一个具有 `api` 和 `write_repository` 权限的 GitLab Personal Access Token	勾选 "Masked and hidden" (隐藏值)

🤔 为什么要这样做？

Masked and hidden 确保 API Key 和 Token 不会在 CI/CD 日志中泄露。
GITLAB_TOKEN_OPENCODE 是 OpenCode 用来创建分支、提交代码和创建 Merge Request 的权限凭证。你可以在 GitLab 用户设置中创建一个新的 Access Token。

✅ 验证：你应该能在 "Variables" 列表中看到这两个变量，它们的值被隐藏显示为 ••••••••。

第 2 步：创建 OpenCode 配置文件目录

🎯 目标：在项目中创建一个专门的目录来存放 OpenCode 的配置和初始提示词。

📝 操作：

在你的项目根目录下，创建一个名为 opencode-config 的目录。

bash

$ mkdir opencode-config

💡 提示：这个目录名 opencode-config 并非固定，你可以自定义，但需要在后续的 .gitlab-ci.yml 文件中保持一致。

✅ 验证：执行 ls 命令，你应该能看到一个名为 opencode-config 的新目录。

第 3 步：配置 GitLab CI/CD 流水线 (CI 组件方式)

🎯 目标：创建一个 .gitlab-ci.yml 文件，引入 OpenCode 的 CI 组件，让 OpenCode 在流水线中运行。

📝 操作：

在项目根目录下创建 .gitlab-ci.yml 文件，并写入以下内容：

yaml

# .gitlab-ci.yml
# 引入社区维护的 OpenCode CI/CD 组件
include:
  - component: $CI_SERVER_FQDN/nagyv/gitlab-opencode/opencode@2
    inputs:
      # 指定 OpenCode 配置文件目录
      config_dir: ${CI_PROJECT_DIR}/opencode-config
      # 引用我们在第 1 步中创建的变量
      auth_json: $OPENCODE_AUTH_JSON
      # 可选：自定义启动命令
      command: optional-custom-command
      # 可选：自定义初始提示词
      message: "Your prompt here"

⚠️ 常见错误：如果你没有 $OPENCODE_AUTH_JSON 这个变量，你需要先创建它。这个变量应该是一个 JSON 格式的字符串，内容如下：

json

{
  "anthropic": {
    "type": "api",
    "key": "$ANTHROPIC_API_KEY"
  }
}

正确做法：在 GitLab CI/CD 变量中，创建一个名为 OPENCODE_AUTH_JSON 的新变量，将上述 JSON 粘贴进去，并确保 $ANTHROPIC_API_KEY 被正确替换为你的实际 Key，或者直接使用变量引用（GitLab 会在运行时自动解析）。

✅ 验证：将此文件推送到 GitLab。你应该能在 CI/CD > Pipelines 中看到一个新的流水线被触发。虽然它可能因为缺少 auth_json 而失败，但这表明我们的配置被 GitLab 正确解析了。

第 4 步：创建 OpenCode 身份验证文件 (高级/备用方式)

🎯 目标：为 OpenCode 创建一个本地的身份验证文件，这是某些高级配置或手动运行 OpenCode 所必需的。

📝 操作：

在 opencode-config 目录下，创建一个名为 auth.json 的文件，并写入以下内容：

json

{
  "anthropic": {
    "type": "api",
    "key": "$ANTHROPIC_API_KEY"
  }
}

💡 提示：这里的 $ANTHROPIC_API_KEY 是一个占位符。当 OpenCode 在 GitLab Runner 上运行时，它会读取环境变量 ANTHROPIC_API_KEY 并将其替换到这个文件中。这是另一种传递 API Key 的方式，比直接在文件中写死更安全。

✅ 验证：执行 cat opencode-config/auth.json 命令，你应该能看到刚刚创建的 JSON 文件内容。

第 5 步：创建 GitLab Duo 流程配置文件 (可选)

🎯 目标：如果你想使用 @opencode 评论触发功能，则需要创建一个更详细的流程配置文件。

📝 操作：

在 opencode-config 目录下，创建一个名为 flow.yml 的文件（或任何你喜欢的名字），并写入以下内容：

yaml

# opencode-config/flow.yml
image: node:22-slim

commands:
  # 1. 安装 OpenCode
  - echo "Installing opencode"
  - npm install --global opencode-ai

  # 2. 安装并配置 glab (GitLab CLI)
  - echo "Installing glab"
  - export GITLAB_TOKEN=$GITLAB_TOKEN_OPENCODE
  - apt-get update --quiet && apt-get install --yes curl wget gpg git && rm --recursive --force /var/lib/apt/lists/*
  - curl --silent --show-error --location "https://raw.githubusercontent.com/upciti/wakemeops/main/assets/install_repository" | bash
  - apt-get install --yes glab

  # 3. 配置 OpenCode 认证
  - echo "Creating OpenCode auth configuration"
  - mkdir --parents ~/.local/share/opencode
  - |
    cat > ~/.local/share/opencode/auth.json << EOF
    {
      "anthropic": {
        "type": "api",
        "key": "$ANTHROPIC_API_KEY"
      }
    }
    EOF

  # 4. 配置 Git 用户信息
  - git config --global user.email "opencode@gitlab.com"
  - git config --global user.name "OpenCode"

  # 5. 运行 OpenCode，并传入上下文
  - |
    opencode run "You are an AI assistant helping with GitLab operations.
    Context: $AI_FLOW_CONTEXT
    Task: $AI_FLOW_INPUT
    Event: $AI_FLOW_EVENT
    Please execute the requested task using the available GitLab tools.
    Be thorough in your analysis and provide clear explanations.
    <important>
    Please use the glab CLI to access data from GitLab. The glab CLI has already been authenticated. You can run the corresponding commands.
    If you are asked to summarize an MR or issue or asked to provide more information then please post back a note to the MR/Issue so that the user can see it.
    You don't need to commit or push up changes, those will be done automatically based on the file changes you make.
    </important>"

  # 6. 自动提交和推送更改
  - git checkout --branch $CI_WORKLOAD_REF origin/$CI_WORKLOAD_REF
  - echo "Checking for git changes and pushing if any exist"
  - |
    if ! git diff --quiet || ! git diff --cached --quiet || [ --not --zero "$(git ls-files --others --exclude-standard)" ]; then
      echo "Git changes detected, adding and pushing..."
      git add .
      if git diff --cached --quiet; then
        echo "No staged changes to commit"
      else
        echo "Committing changes to branch: $CI_WORKLOAD_REF"
        git commit --message "Codex changes"
        echo "Pushing changes up to $CI_WORKLOAD_REF"
        git push https://gitlab-ci-token:$GITLAB_TOKEN@$CI_SERVER_HOST/$CI_PROJECT_PATH.git $CI_WORKLOAD_REF
        echo "Changes successfully pushed"
      fi
    else
      echo "No git changes detected, skipping push"
    fi

🤔 为什么要这样做？

这个配置文件定义了 OpenCode 在 GitLab Runner 上运行时的完整环境。
glab 是 GitLab 的官方 CLI 工具，允许 OpenCode 通过命令行与 GitLab API 交互（例如，读取 Issue、创建 MR）。
$AI_FLOW_CONTEXT, $AI_FLOW_INPUT, $AI_FLOW_EVENT 是 GitLab Duo 流程自动注入的变量，它们提供了当前 Issue/MR 的上下文信息。
最后的 git 命令块实现了自动提交和推送代码，这是 OpenCode 能够“修复 Issue”的关键。

✅ 验证：执行 cat opencode-config/flow.yml 命令，你应该能看到刚刚创建的配置文件内容。

第 6 步：验证与测试

🎯 目标：通过一个真实的 GitLab Issue 来测试 OpenCode 的集成是否成功。

📝 操作：

在你的 GitLab 项目中创建一个新的 Issue。
在 Issue 的评论区输入以下内容并点击 Comment：
```
@opencode explain this issue
```
等待几秒钟，刷新页面。你应该能看到 OpenCode 对 Issue 的分析和解释。

✅ 验证：

你应该会看到一条新的评论，来自名为 opencode 的机器人账号，内容是对 Issue 的详细解释。
在 CI/CD > Pipelines 中，你应该能看到一条由 @opencode 评论触发的流水线正在运行。

⚠️ 常见错误：如果 OpenCode 没有响应，请检查以下几点：

GitLab Runner 状态：确保你的 Runner 是活跃的，并且可以执行作业。
API Key 有效性：检查 ANTHROPIC_API_KEY 或 OPENAI_API_KEY 是否正确且未过期。
Token 权限：确保 GITLAB_TOKEN_OPENCODE 具有 api 和 write_repository 权限。
流水线日志：查看失败的流水线作业日志，通常能找到具体的错误原因。

进阶技巧（可选）

掌握基础后，你可以尝试：

自定义触发词：在 GitLab Duo 配置中，你可以将 @opencode 修改为任何你喜欢的词，例如 @ai-assistant。
限制 OpenCode 的作用域：通过配置，你可以让 OpenCode 只对特定标签（如 bug）的 Issue 做出响应，或者只对特定分支的 Merge Request 进行审查。
使用不同的 AI 模型：在 auth.json 中，你可以配置多个模型提供商，并在运行时指定使用哪一个。

常见问题 (FAQ)

Q1: 报错 component not found 怎么办？A: 这通常意味着 GitLab 实例无法访问到该组件仓库。请确认你的 GitLab 版本是否支持 CI 组件功能（GitLab 15.6+），并且网络可以访问到 $CI_SERVER_FQDN 上的组件。

Q2: OpenCode 无法创建 Merge Request？A: 请检查 GITLAB_TOKEN_OPENCODE 的权限。它必须拥有 write_repository 作用域。此外，确保流水线配置中 git push 命令使用的 URL 是正确的。

Q3: 如何让 OpenCode 在私有 GitLab Runner 上运行？A: 本教程中的配置默认使用 GitLab 共享 Runner。如果你想使用私有 Runner，只需确保你的 Runner 标签（Tag）与 .gitlab-ci.yml 中指定的标签匹配即可。

总结

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

两种集成方式：我们学习了如何通过 CI 组件和 GitLab Duo 流程配置文件来集成 OpenCode。
安全配置：我们掌握了如何安全地存储 API Key 和 GitLab Token 作为 CI/CD 变量。
自动化工作流：我们成功配置了 @opencode 机器人，它可以解释 Issue、修复 Bug 和审查代码。
底层原理：我们理解了 OpenCode 如何通过 glab CLI 与 GitLab 交互，以及 CI 流水线如何自动化整个流程。

GitLab + OpenCode AI 自动化工作流实战教程：配置CI/CD与Duo机器人 ​

你将学到什么 ​

最终效果 ​

前置准备 ​

1. 获取 AI 模型 API Key ​

第 1 步：配置 GitLab CI/CD 变量 ​

第 2 步：创建 OpenCode 配置文件目录 ​

第 3 步：配置 GitLab CI/CD 流水线 (CI 组件方式) ​

第 4 步：创建 OpenCode 身份验证文件 (高级/备用方式) ​

第 5 步：创建 GitLab Duo 流程配置文件 (可选) ​

第 6 步：验证与测试 ​

进阶技巧（可选） ​

常见问题 (FAQ) ​

总结 ​

GitLab + OpenCode AI 自动化工作流实战教程：配置CI/CD与Duo机器人

你将学到什么

最终效果

前置准备

1. 获取 AI 模型 API Key

第 1 步：配置 GitLab CI/CD 变量

第 2 步：创建 OpenCode 配置文件目录

第 3 步：配置 GitLab CI/CD 流水线 (CI 组件方式)

第 4 步：创建 OpenCode 身份验证文件 (高级/备用方式)

第 5 步：创建 GitLab Duo 流程配置文件 (可选)

第 6 步：验证与测试

进阶技巧（可选）

常见问题 (FAQ)

总结