CodeBuddy Code GitLab CI/CD 集成

概述

CodeBuddy Code 支持与 GitLab CI/CD 深度集成，让您能够在 CI/CD 流水线中使用 AI 辅助完成代码审查、自动化实现和智能优化等任务。该集成基于 CodeBuddy Code CLI 构建，可在 GitLab CI 作业中以编程方式使用 AI 能力。

为什么在 GitLab CI/CD 中使用 CodeBuddy Code?

即时创建 MR：描述您的需求，CodeBuddy 自动生成完整的合并请求及变更说明
自动化实现：通过简单的命令或评论，将 Issue 转化为可工作的代码
项目感知: CodeBuddy 遵循您的 CODEBUDDY.md 指南和现有代码规范
简单配置：只需在 .gitlab-ci.yml 中添加一个作业和必要的 CI/CD 变量
默认安全：在您的 GitLab Runner 中运行，遵循分支保护和审批流程

工作原理

CodeBuddy Code 利用 GitLab CI/CD 在隔离的作业中运行 AI 任务，并通过 MR 提交结果：

事件驱动编排: GitLab 监听您选择的触发器（例如 Issue、MR 或评论中提及 @codebuddy)。作业收集上下文和代码库信息，构建提示并运行 CodeBuddy Code。
沙箱执行：每次交互都在具有严格网络和文件系统规则的容器中运行。CodeBuddy Code 强制执行工作区范围的权限约束写入。每个变更都通过 MR 流转，审查者可以看到差异，审批流程仍然适用。

CodeBuddy 能做什么？

CodeBuddy Code 支持强大的 CI/CD 工作流，改变您与代码的协作方式：

从 Issue 描述或评论创建和更新 MR
分析性能回归并提出优化建议
直接在分支中实现功能，然后创建 MR
修复测试或评论中发现的 Bug 和回归问题
响应后续评论以迭代完善请求的变更

配置指南

快速配置

最快的入门方式是在 .gitlab-ci.yml 中添加一个最小化的作业，并将 API 密钥设置为受保护的变量。

步骤 1：添加受保护的 CI/CD 变量

进入 GitLab 项目的 设置 → CI/CD → 变量，添加以下环境变量：

认证配置：

在 GitLab 项目的 设置 → CI/CD → 变量 中添加以下环境变量：

CODEBUDDY_API_KEY （必需）
- 用于模型接口调用的 API 密钥
- 配置时勾选： ✅ 受保护（Protect variable)、✅ 已屏蔽（Mask variable)

可选配置：

CODEBUDDY_INTERNET_ENVIRONMENT
- 网络环境配置（中国版用户需要设置为 internal,iOA 用户设置为 iOA)
CODEBUDDY_BASE_URL
- 自定义模型服务的基础 URL（需兼容 OpenAI 接口协议）
GITLAB_ACCESS_TOKEN
- GitLab 项目访问令牌（需具有 api 范围）
- 用于 CodeBuddy 创建/更新 MR 和评论
- 如不配置，默认使用 CI_JOB_TOKEN
- 配置时勾选： ✅ 受保护、✅ 已屏蔽

📖 完整配置指南：根据您的账号类型，查看对应的配置方法和 API KEY 获取地址：
iOA 账号用户（公司内部）：参考 iOA 账号使用 API KEY
中国版用户：参考中国版使用 API KEY
海外版用户：参考海外版使用 API KEY
每个章节包含完整的环境变量配置方法和 API KEY 获取地址。

步骤 2：在 .gitlab-ci.yml 中添加 CodeBuddy 作业

yaml

stages:
  - ai

codebuddy:
  stage: ai
  image: node:24-alpine3.21
  # 根据需要调整触发规则：
  # - 手动运行
  # - 合并请求事件
  # - 当评论包含 '@codebuddy' 时通过 Web/API 触发
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  variables:
    GIT_STRATEGY: fetch
    # CODEBUDDY_API_KEY 从 CI/CD 变量中自动注入
    # 可选变量： CODEBUDDY_BASE_URL, GITLAB_ACCESS_TOKEN
  before_script:
    - apk update
    - apk add --no-cache git curl bash
    - npm install -g @tencent-ai/codebuddy-code
    # 验证 CODEBUDDY_API_KEY 已设置
    - |
      if [ -z "$CODEBUDDY_API_KEY" ]; then
        echo "错误: CODEBUDDY_API_KEY 未设置。请在 GitLab CI/CD 变量中配置"
        exit 1
      fi
  script:
    # 可选： 启动 GitLab MCP 服务器（如果您的环境提供）
    - /bin/gitlab-mcp-server || true
    # 使用 AI_FLOW_* 变量时通过 web/API 触发器传递上下文
    - echo "$AI_FLOW_INPUT for $AI_FLOW_CONTEXT on $AI_FLOW_EVENT"
    - >
      codebuddy
      -p "${AI_FLOW_INPUT:-'审查此 MR 并实现请求的变更'}"
      --permission-mode acceptEdits
      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
      --debug

添加作业和 API 密钥变量后，通过 CI/CD → 流水线手动运行作业进行测试，或从 MR 触发它，让 CodeBuddy 在分支中提出更新并在需要时创建 MR。

手动配置（推荐用于生产环境）

如果您需要更精细的控制：

添加 GitLab API 操作的项目凭据:
- 默认使用 CI_JOB_TOKEN,或创建具有 api 范围的项目访问令牌
- 如果使用 PAT,将其存储为 GITLAB_ACCESS_TOKEN（已屏蔽）
在 .gitlab-ci.yml 中添加 CodeBuddy 作业（参见上面的示例）
（可选）启用提及驱动的触发器:
- 为"评论(notes)"添加项目 Webhook 到您的事件监听器（如果使用）
- 让监听器在评论包含 @codebuddy 时调用流水线触发 API,传递 AI_FLOW_INPUT 和 AI_FLOW_CONTEXT 等变量

使用示例

将 Issue 转化为 MR

在 Issue 评论中：

@codebuddy 根据 Issue 描述实现此功能

CodeBuddy 分析 Issue 和代码库，在分支中编写变更，并创建 MR 供审查。

获取实现帮助

在 MR 讨论中：

@codebuddy 建议一个具体的方法来缓存此 API 调用的结果

CodeBuddy 提出变更方案，添加适当的缓存代码，并更新 MR。

快速修复 Bug

在 Issue 或 MR 评论中：

@codebuddy 修复用户仪表板组件中的 TypeError

CodeBuddy 定位 Bug,实现修复，并更新分支或创建新的 MR。

最佳实践

CODEBUDDY.md 配置

在仓库根目录创建 CODEBUDDY.md 文件，定义编码标准、审查标准和项目特定规则。CodeBuddy 在运行期间会读取此文件，并在提出变更时遵循您的约定。

示例 CODEBUDDY.md:

markdown

# 项目编码规范

## 代码风格
- 使用 ESLint 和 Prettier 进行代码格式化
- 遵循 Airbnb JavaScript 风格指南
- 使用 TypeScript 严格模式

## 提交规范
- 遵循 Conventional Commits 规范
- 提交信息使用中文
- 每个提交只包含一个逻辑变更

## 测试要求
- 所有新功能必须包含单元测试
- 测试覆盖率不低于 80%
- 使用 Jest 作为测试框架

## MR 审查清单
- 代码通过所有 CI 检查
- 至少一名团队成员审查通过
- 更新相关文档

安全考虑

永远不要将敏感信息提交到仓库！ 始终使用 GitLab CI/CD 变量：

将敏感配置添加为已屏蔽的变量（如有需要，标记为受保护）
限制作业权限和网络出口
像审查其他贡献者一样审查 CodeBuddy 的 MR

性能优化

保持 CODEBUDDY.md 简洁明了
提供清晰的 Issue/MR 描述以减少迭代
配置合理的作业超时以避免失控运行
在 Runner 中缓存 npm 和包安装（如果可能）

CI 成本控制

使用 CodeBuddy Code 与 GitLab CI/CD 时，请注意相关成本：

GitLab Runner 时间：

CodeBuddy 在您的 GitLab Runner 上运行并消耗计算分钟
查看您的 GitLab 计划的 Runner 计费详情

成本优化建议：

使用具体的 @codebuddy 命令以减少不必要的轮次
设置适当的 --max-turns 和作业超时值
限制并发以控制并行运行

安全与治理

每个作业在具有受限网络访问的隔离容器中运行
CodeBuddy 的变更通过 MR 流转，审查者可以看到每个差异
分支保护和审批规则适用于 AI 生成的代码
CodeBuddy Code 使用工作区范围的权限约束写入

故障排除

CodeBuddy 不响应 @codebuddy 命令

验证您的流水线正在被触发（手动、MR 事件或通过备注事件监听器/Webhook)
确保 CI/CD 变量存在且配置正确
检查评论是否包含 @codebuddy（不是 /codebuddy)并且您的提及触发器已配置

作业无法写入评论或创建 MR

确保 CI_JOB_TOKEN 对项目有足够的权限，或使用具有 api 范围的项目访问令牌
检查 mcp__gitlab 工具在 --allowedTools 中已启用
确认作业在 MR 上下文中运行或通过 AI_FLOW_* 变量有足够的上下文

身份验证错误

认证变量未设置：

确认已在 GitLab 项目的 设置 → CI/CD → 变量 中添加 CODEBUDDY_API_KEY
检查变量名称拼写是否正确（区分大小写）
如果设置了"受保护"选项，确保作业在受保护的分支上运行

API 认证失败（401 Unauthorized）:

验证 API 密钥是否有效且未过期
确认复制 API 密钥时没有包含额外的空格或换行符
检查 API 密钥的权限范围是否足够
查看 [设置配置文档](settings.md#认证配置）了解详细配置方法

API 连接失败：

检查 CODEBUDDY_BASE_URL 是否配置正确（如使用自定义端点）
验证 GitLab Runner 能否访问 CodeBuddy API 服务器
确认 URL 格式正确，包含协议（如 https://api.example.com）

密钥在日志中可见：

确保在 CI/CD 变量配置时勾选了 ✅ 已屏蔽（Mask variable)
避免在脚本中直接 echo 或打印 API 密钥

GitLab Access Token 相关问题：

检查配置的 CI/CD 变量是否正确设置
验证相关的访问权限配置
确保 CI_JOB_TOKEN 或 GITLAB_ACCESS_TOKEN 具有足够的权限(api 范围）

作业超时

增加作业的 timeout 配置
简化提示以减少处理时间
考虑将大任务拆分为多个小任务

高级配置

常用参数和变量

环境变量：

CodeBuddy Code 在 CI/CD 环境中使用以下环境变量：

认证配置：

CODEBUDDY_API_KEY：用于模型接口调用，适合 CI/CD 非交互环境

可选配置：

CODEBUDDY_BASE_URL：自定义模型服务的基础 URL
GITLAB_ACCESS_TOKEN: GitLab API 访问令牌（用于 MR 操作）
CI_JOB_TOKEN: GitLab CI 自动提供的作业令牌

流程控制变量：

AI_FLOW_INPUT：通过 Web/API 触发器传递的用户输入
AI_FLOW_CONTEXT：上下文信息（如 Issue ID、MR ID 等）
AI_FLOW_EVENT：触发事件类型（如 note、issue、merge_request）

📖 关于各环境变量的详细说明和配置示例，请参考 [设置配置文档](settings.md#环境变量）

命令行参数：

CodeBuddy Code 支持这些常用输入：

prompt (-p)：内联提供指令
max-turns：限制来回迭代的次数
permission-mode：权限模式（如 acceptEdits)
allowedTools：允许使用的工具列表
debug：启用调试输出

注意： 确切的标志和参数可能因 @tencent-ai/codebuddy-code 版本而异。在作业中运行 codebuddy --help 查看支持的选项。

自定义 CodeBuddy 行为

您可以通过两种主要方式指导 CodeBuddy:

CODEBUDDY.md：定义编码标准、安全要求和项目约定。CodeBuddy 在运行期间读取此文件并遵循您的规则。
自定义提示：通过作业中的 prompt/prompt_file 传递特定于任务的指令。对不同的作业使用不同的提示（例如审查、实现、重构）。

多环境配置

您可以为不同的环境（开发、测试、生产）配置不同的 CodeBuddy 作业：

yaml

# 开发环境 - 自动触发
codebuddy-dev:
  stage: ai
  rules:
    - if: '$CI_COMMIT_BRANCH == "develop"'
  script:
    - codebuddy -p "快速审查并自动合并"

# 生产环境 - 手动触发
codebuddy-prod:
  stage: ai
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual
  script:
    - codebuddy -p "详细审查，生成完整的变更报告"

参考资源

让 AI 赋能您的 CI/CD 流水线，提升开发效率！

CodeBuddy Code GitLab CI/CD 集成 ​

概述 ​

为什么在 GitLab CI/CD 中使用 CodeBuddy Code? ​

工作原理 ​

CodeBuddy 能做什么？ ​

配置指南 ​

快速配置 ​

手动配置（推荐用于生产环境） ​

使用示例 ​

将 Issue 转化为 MR ​

获取实现帮助 ​

快速修复 Bug ​

最佳实践 ​

CODEBUDDY.md 配置 ​

安全考虑 ​

性能优化 ​

CI 成本控制 ​

安全与治理 ​

故障排除 ​

CodeBuddy 不响应 @codebuddy 命令 ​

作业无法写入评论或创建 MR ​

身份验证错误 ​

作业超时 ​

高级配置 ​

常用参数和变量 ​

自定义 CodeBuddy 行为 ​

多环境配置 ​

参考资源 ​