# CodeBuddy Code GitLab CI/CD 集成

## 概述

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


## 工作原理

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 获取地址：
> - **iOA 账号用户**（公司内部）：参考 [iOA 账号使用 API KEY](settings.md#ioa-账号使用-api-key)
> - **中国版用户**：参考 [中国版使用 API KEY](settings.md#中国版使用-api-key)
> - **海外版用户**：参考 [海外版使用 API KEY](settings.md#海外版使用-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。

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

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

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:
```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:

1. **CODEBUDDY.md**：定义编码标准、安全要求和项目约定。CodeBuddy 在运行期间读取此文件并遵循您的规则。

2. **自定义提示**：通过作业中的 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 "详细审查，生成完整的变更报告"
```

---

## 参考资源

- [CodeBuddy Code 官方文档](./README.md)
- [CLI 参考](cli-reference.md)
- [设置配置](settings.md)
- [常见工作流](common-workflows.md)
- [故障排除](troubleshooting.md)

---

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