CodeBuddy Code 支持与 GitLab CI/CD 深度集成，让您能够在 CI/CD 流水线中使用 AI 辅助完成代码审查、自动化实现和智能优化等任务。该集成基于 CodeBuddy Code CLI 构建，可在 GitLab CI 作业中以编程方式使用 AI 能力。
即时创建 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 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 获取地址。
步骤 2：在 .gitlab-ci.yml 中添加 CodeBuddy 作业
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 评论中：
@codebuddy 根据 Issue 描述实现此功能
CodeBuddy 分析 Issue 和代码库，在分支中编写变更，并创建 MR 供审查。
在 MR 讨论中：
@codebuddy 建议一个具体的方法来缓存此 API 调用的结果
CodeBuddy 提出变更方案，添加适当的缓存代码，并更新 MR。
在 Issue 或 MR 评论中：
@codebuddy 修复用户仪表板组件中的 TypeError
CodeBuddy 定位 Bug，实现修复，并更新分支或创建新的 MR。
在仓库根目录创建 CODEBUDDY.md 文件，定义编码标准、审查标准和项目特定规则。CodeBuddy 在运行期间会读取此文件，并在提出变更时遵循您的约定。
示例 CODEBUDDY.md:
# 项目编码规范
## 代码风格
- 使用 ESLint 和 Prettier 进行代码格式化
- 遵循 Airbnb JavaScript 风格指南
- 使用 TypeScript 严格模式
## 提交规范
- 遵循 Conventional Commits 规范
- 提交信息使用中文
- 每个提交只包含一个逻辑变更
## 测试要求
- 所有新功能必须包含单元测试
- 测试覆盖率不低于 80%
- 使用 Jest 作为测试框架
## MR 审查清单
- 代码通过所有 CI 检查
- 至少一名团队成员审查通过
- 更新相关文档
永远不要将敏感信息提交到仓库！ 始终使用 GitLab CI/CD 变量：
将敏感配置添加为已屏蔽的变量（如有需要，标记为受保护）
限制作业权限和网络出口
像审查其他贡献者一样审查 CodeBuddy 的 MR
保持 CODEBUDDY.md 简洁明了
提供清晰的 Issue/MR 描述以减少迭代
配置合理的作业超时以避免失控运行
在 Runner 中缓存 npm 和包安装（如果可能）
使用 CodeBuddy Code 与 GitLab CI/CD 时，请注意相关成本：
GitLab Runner 时间：
CodeBuddy 在您的 GitLab Runner 上运行并消耗计算分钟
查看您的 GitLab 计划的 Runner 计费详情
成本优化建议：
使用具体的 @codebuddy 命令以减少不必要的轮次
设置适当的 --max-turns 和作业超时值
限制并发以控制并行运行
每个作业在具有受限网络访问的隔离容器中运行
CodeBuddy 的变更通过 MR 流转，审查者可以看到每个差异
分支保护和审批规则适用于 AI 生成的代码
CodeBuddy Code 使用工作区范围的权限约束写入
验证您的流水线正在被触发（手动、MR 事件或通过备注事件监听器/Webhook)
确保 CI/CD 变量存在且配置正确
检查评论是否包含 @codebuddy（不是 /codebuddy)并且您的提及触发器已配置
确保 CI_JOB_TOKEN 对项目有足够的权限，或使用具有 api 范围的项目访问令牌
检查 mcp__gitlab 工具在 --allowedTools 中已启用
确认作业在 MR 上下文中运行或通过 AI_FLOW_* 变量有足够的上下文
认证变量未设置：
确认已在 GitLab 项目的 设置 > CI/CD > 变量 中添加 CODEBUDDY_API_KEY
检查变量名称拼写是否正确（区分大小写）
如果设置了"受保护"选项，确保作业在受保护的分支上运行
API 认证失败（401 Unauthorized）:
验证 API 密钥是否有效且未过期
确认复制 API 密钥时没有包含额外的空格或换行符
检查 API 密钥的权限范围是否足够
查看 设置配置文档 了解详细配置方法
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）
命令行参数：
CodeBuddy Code 支持这些常用输入：
prompt (-p)：内联提供指令
max-turns：限制来回迭代的次数
permission-mode：权限模式（如 acceptEdits)
allowedTools：允许使用的工具列表
debug：启用调试输出
注意：
确切的标志和参数可能因 @tencent-ai/codebuddy-code 版本而异。在作业中运行 codebuddy --help 查看支持的选项。
您可以通过两种主要方式指导 CodeBuddy:
CODEBUDDY.md：定义编码标准、安全要求和项目约定。CodeBuddy 在运行期间读取此文件并遵循您的规则。
自定义提示：通过作业中的 prompt/prompt_file 传递特定于任务的指令。对不同的作业使用不同的提示（例如审查、实现、重构）。
您可以为不同的环境（开发、测试、生产）配置不同的 CodeBuddy 作业：
# 开发环境 - 自动触发
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 "详细审查，生成完整的变更报告"
