概述
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 提交结果:
1. 事件驱动编排: GitLab 监听您选择的触发器(例如 Issue、MR 或评论中提及 @codebuddy)。作业收集上下文和代码库信息,构建提示并运行 CodeBuddy Code。
2. 沙箱执行:每次交互都在具有严格网络和文件系统规则的容器中运行。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 获取地址。
步骤 2:在 .gitlab-ci.yml 中添加 CodeBuddy 作业
stages:- aicodebuddy:stage: aiimage: 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_TOKENbefore_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" ]; thenecho "错误: CODEBUDDY_API_KEY 未设置。请在 GitLab CI/CD 变量中配置"exit 1fiscript:# 可选: 启动 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。
手动配置(推荐用于生产环境)
如果您需要更精细的控制:
1. 添加 GitLab API 操作的项目凭据:
默认使用 CI_JOB_TOKEN,或创建具有 api 范围的项目访问令牌
如果使用 PAT,将其存储为 GITLAB_ACCESS_TOKEN(已屏蔽)
2. 在 .gitlab-ci.yml 中添加 CodeBuddy 作业(参见上面的示例)
3. (可选)启用提及驱动的触发器:
为"评论(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:
# 项目编码规范## 代码风格- 使用 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 密钥的权限范围是否足够
查看 设置配置文档 了解详细配置方法
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:自定义模型服务的基础 URLGITLAB_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:
1. CODEBUDDY.md:定义编码标准、安全要求和项目约定。CodeBuddy 在运行期间读取此文件并遵循您的规则。
2. 自定义提示:通过作业中的 prompt/prompt_file 传递特定于任务的指令。对不同的作业使用不同的提示(例如审查、实现、重构)。
多环境配置
您可以为不同的环境(开发、测试、生产)配置不同的 CodeBuddy 作业:
# 开发环境 - 自动触发codebuddy-dev:stage: airules:- if: '$CI_COMMIT_BRANCH == "develop"'script:- codebuddy -p "快速审查并自动合并"# 生产环境 - 手动触发codebuddy-prod:stage: airules:- if: '$CI_COMMIT_BRANCH == "main"'when: manualscript:- codebuddy -p "详细审查,生成完整的变更报告"