二、为什么在 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: 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。
七、手动配置（推荐用于生产环境）
如果你需要更精细的控制：
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)并且你的提及触发器已配置
20、作业无法写入评论或创建 MR
·确保 CI_JOB_TOKEN 对项目有足够的权限，或使用具有 api 范围的项目访问令牌
·检查 mcp__gitlab 工具在 –allowedTools 中已启用
·确认作业在 MR 上下文中运行或通过 AI_FLOW_* 变量有足够的上下文
21、身份验证错误
认证变量未设置：
·确认已在 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 范围）
22、作业超时
·增加作业的 timeout 配置
·简化提示以减少处理时间
·考虑将大任务拆分为多个小任务
24、常用参数和变量
环境变量：
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 查看支持的选项。
25、自定义 CodeBuddy 行为
你可以通过两种主要方式指导 CodeBuddy:
1. CODEBUDDY.md：定义编码标准、安全要求和项目约定。CodeBuddy 在运行期间读取此文件并遵循你的规则。
2. 自定义提示：通过作业中的 prompt/prompt_file 传递特定于任务的指令。对不同的作业使用不同的提示（例如审查、实现、重构）。
26、多环境配置
你可以为不同的环境（开发、测试、生产）配置不同的 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 "详细审查，生成完整的变更报告"