比特桶自动PR审查器

Name: 比特桶自动PR审查器
Author: TinTinWinata

作者：TinTinWinata2 星标更新：2025-11-20

安装使用来源：spider==github.com

项目介绍

使用Claude CLI进行PR自动化

一个基于Docker的简单自动化服务，接收Bitbucket的拉取请求（PR）webhook，克隆/验证仓库，并使用Claude CLI（而非API）处理它们。

功能

🔗 接收Bitbucket PR创建webhook
🔒 验证webhook签名及工作区限制（xriopteam）
📦 自动克隆仓库（如果尚未存在）
🔄 更新现有仓库后再进行处理
🤖 使用Claude CLI处理PR数据（--dangerously-skip-permissions）
🐳 完全容器化，使用Docker
⚡ 使用Express.js REST API
📝 环境变量配置简便
📊 集成Prometheus指标用于监控

前提条件

已安装Docker和Docker Compose
具有webhook访问权限的Bitbucket仓库
Bitbucket凭证（应用密码令牌和用户名）

注意： 此处使用的是Claude CLI（在Docker中全局安装），不是Anthropic API，因此不需要API密钥！

快速开始

📖 完整设置说明，请参见 SETUP_GUIDE.md

快速开始命令

# 交互式设置（推荐）
npm run setup

# 或者在配置后手动启动
docker-compose up -d

所需内容

✅ 已安装Docker和Docker Compose
✅ 具有webhook访问权限的Bitbucket仓库
✅ 全局安装Claude CLI：npm install -g @anthropic-ai/claude-code

配置Bitbucket Webhook

转到你的Bitbucket仓库设置
导航至Webhooks部分
点击添加webhook
配置：
- 标题：PR Automation
- URL：http://your-server:3000/webhook/bitbucket/pr
- 状态：活动
- 触发器：选择“拉取请求”→“创建”
保存webhook

工作原理

流程

接收到webhook：当创建PR时，Bitbucket发送webhook
项目验证：系统检查仓库是否已克隆到/app/projects
- 如果未克隆：从Bitbucket克隆仓库
- 如果已存在：更新仓库（git pull）
Claude CLI处理：执行claude --dangerously-skip-permissions与提示
- 在项目目录中运行，具有终端访问权限
- 可以执行git命令、读取文件、分析代码
- 输出文本形式的审查结果
响应：Claude的分析被记录（可以扩展为发布评论等）

Claude CLI vs API

此实现使用Claude CLI而不是Anthropic API：

功能	Claude CLI	Anthropic API
认证	使用CLI会话（无需API密钥）	需要`ANTHROPIC_API_KEY`
功能	拥有完整的终端访问权限，可执行命令	仅限文本，无法执行命令
安装	`npm install -g @anthropic-ai/claude-code`	`npm install @anthropic-ai/sdk`
自动化	使用`--dangerously-skip-permissions`	直接调用API
成本	免费（使用Claude CLI会话）	按token计费

项目结构

@pr-automation/
├── src/
│   ├── index.js          # Express服务器和webhook处理器
│   ├── claude.js         # Claude CLI集成与验证
│   ├── git.js            # Git操作（克隆、更新、验证）
│   ├── metrics.js        # Prometheus指标收集
│   ├── logger.js         # 日志配置
│   └── template-manager.js # PR审查模板管理
├── tests/                # 单元测试目录
│   ├── claude.test.js    # 对Claude.js功能的测试
│   ├── git.test.js       # 对Git操作的测试
│   └── metrics.test.js   # 对指标收集的测试
├── projects/             # 克隆的仓库（卷挂载）
├── Dockerfile            # 安装了Claude CLI的Docker镜像
├── docker-compose.yml    # Docker Compose设置
├── jest.config.json      # Jest测试配置
├── package.json          # Node.js依赖项和脚本
├── .env.example          # 环境变量模板
└── README.md             # 本文档

API端点

健康检查

GET /health

返回服务状态。

响应：

{
  "status": "ok",
  "message": "PR自动化服务正在运行"
}

Bitbucket PR Webhook

POST /webhook/bitbucket/pr

接收Bitbucket拉取请求创建webhook。

预期头信息：

x-event-key：应为pullrequest:created

响应：

{
  "message": "成功接收webhook",
  "prTitle": "添加新功能"
}

自定义PR审查模板

该系统支持模块化的模板，以便在不更改代码的情况下自定义审查行为。

快速模板设置

1. 创建自定义模板：

touch src/templates/custom/my-review.md

2. 编写带有变量的模板：

**角色**：您是一位专注于安全的代码审查员。
**目标**：审查{{repository}}中的漏洞。
**PR**：`{{prUrl}}`

## 安全检查清单
- 检查SQL注入
- 验证输入验证
- 审查身份验证逻辑

## 最终步骤：输出指标
```json
{"isLgtm": true/false, "issueCount": 0}

3. 将仓库映射到模板：

// src/config/template-config.json
{
  "defaultTemplate": "default",
  "repositories": {
    "payment-api": "my-review"
  }
}

4. 重启服务：

docker-compose restart pr-automation

可用变量

在您的模板中使用这些变量：{{prUrl}}，{{title}}，{{author}}，{{repository}}，{{sourceBranch}}，{{destinationBranch}}，{{description}}

内置示例模板

security-focused - 安全漏洞分析
performance-review - 性能瓶颈检测
quick-review - 快速审查小改动

完整文档

📖 参见 TEMPLATE_GUIDE.md。

测试

该项目包含全面的单元测试，以确保代码质量和可靠性。

运行测试

# 安装依赖项
npm install

# 运行所有测试
npm test

# 在监视模式下运行测试（文件更改时自动重新运行）
npm run test:watch

# 运行测试并生成覆盖率报告
npm run test:coverage

开发

不使用Docker运行

# 全局安装Claude CLI
npm install -g @anthropic-ai/claude-code

# 安装依赖项
npm install

# 运行测试以验证设置
npm test

# 创建projects目录
mkdir projects

# 以开发模式启动，自动重载
npm run dev

使用Docker运行（开发）

docker-compose.yml包括热重载的卷挂载：

docker-compose up

Claude CLI命令

系统执行Claude CLI如下：

claude --dangerously-skip-permissions \
  -p "$(cat prompt.txt)" \
  --model "sonnet" \
  --output-format text

标志解释：

--dangerously-skip-permissions：跳过交互式批准提示（自动化所需）
-p：从文件提供提示
--model：选择模型（haiku, sonnet, opus）
--output-format text：获取纯文本输出

Git操作

系统自动处理Git操作：

克隆：如果仓库不存在，则从Bitbucket克隆
更新：如果仓库已存在，则拉取最新更改
认证：使用来自环境变量的令牌和用户名

支持的认证方法

应用密码（令牌+用户）：

BITBUCKET_USER=your-username
BITBUCKET_TOKEN=your-token-here

环境变量

变量	必填	默认值	描述
`CLAUDE_MODEL`	否	`sonnet`	Claude模型：`haiku`，`sonnet`或`opus`
`BITBUCKET_TOKEN`	是	-	Bitbucket应用密码或令牌
`BITBUCKET_USER`	是	-	Bitbucket用户名
`BITBUCKET_WEBHOOK_SECRET`	推荐	-	Webhook签名验证密钥
`ALLOWED_WORKSPACE`	否	`xriopteam`	接受webhook的Bitbucket工作区/组织slug
`PROCESS_ONLY_CREATED`	否	`false`	设置为`true`仅处理PR创建事件（忽略更新）
`PORT`	否	`3000`	服务器端口
`METRICS_PERSISTENCE_ENABLED`	否	`false`	启用指标持久性以在重启/重建后保留
`METRICS_PERSISTENCE_TYPE`	否	`filesystem`	存储类型：`filesystem`或`sqlite`
`METRICS_PERSISTENCE_PATH`	否	`./metrics-storage`	存储指标数据的路径
`METRICS_PERSISTENCE_SAVE_INTERVAL_MS`	否	`30000`	保存间隔（毫秒，30秒）

故障排除

检查服务是否运行

curl http://localhost:3000/health

查看日志

docker-compose logs -f pr-automation

在容器中测试Claude CLI

docker-compose exec pr-automation sh
claude --help

检查克隆的项目

docker-compose exec pr-automation ls -la /app/projects

手动测试git克隆

docker-compose exec pr-automation sh
cd /app/projects
git clone https://x-token-auth:YOUR_TOKEN@bitbucket.org/your-workspace/your-repo.git

重启服务

docker-compose restart

更改后重建

docker-compose down
docker-compose build --no-cache
docker-compose up -d

停止服务

docker-compose down

清除所有项目（重置）

rm -rf projects/*
docker-compose restart

Webhook安全性

Webhook端点通过两层保护来保证安全：

1. 签名验证

所有webhook请求必须在X-Hub-Signature头中包含有效的HMAC-SHA256签名。这确保请求确实来自Bitbucket。

2. 工作区限制

仅接受来自xriopteamBitbucket工作区的webhook。这防止其他组织未经授权的访问。

设置

生成webhook密钥：
```
openssl rand -hex 32
```

添加到.env文件：

BITBUCKET_WEBHOOK_SECRET=your-generated-secret
ALLOWED_WORKSPACE=xriopteam

在Bitbucket中配置：
- 转到仓库设置 → Webhooks
- 添加webhook URL：https://bitbucket.tintinwinata.online/webhook/bitbucket/pr
- 在“密钥”字段中添加相同的密钥
- 选择触发器：PR创建，PR更新
重启服务：
```
docker compose restart pr-automation
```

📖 详细配置和故障排除，请参见 WEBHOOK_SECURITY.md。

使用Prometheus监控

应用程序在/metrics端点暴露Prometheus指标，用于监控PR自动化活动和Claude审查性能。

可用指标

PR创建：pr_created_total - 创建的PR数量
PR更新：pr_updated_total - 更新的PR数量
LGTM计数：claude_lgtm_total - Claude批准的数量
发现的问题：claude_issues_found_total - 发现的所有问题总数（例如，如果1个PR有3个问题，则计数加3）
成功的审查：claude_review_success_total - 成功审查的PR数量
失败的审查：claude_review_failure_total - 失败的审查（带错误类型）
审查持续时间：claude_review_duration_seconds - 审查持续时间直方图

访问指标

curl http://localhost:3000/metrics

详细文档

参见 PROMETHEUS.md 了解：

详细的指标描述
Grafana仪表盘示例
示例PromQL查询

注意：Prometheus已在/workspace/monitoring/prometheus.yml中配置，以从pr-automation:3000抓取指标。

指标持久性

默认情况下，指标存储在内存中，并在应用程序重启时重置。您可以启用指标持久性以在重启和容器重建后保留指标。

启用指标持久性

在您的.env文件中添加这些环境变量：

METRICS_PERSISTENCE_ENABLED=true
METRICS_PERSISTENCE_TYPE=filesystem
METRICS_PERSISTENCE_PATH=./metrics-storage
METRICS_PERSISTENCE_SAVE_INTERVAL_MS=30000

存储类型

文件系统（适用于大多数用例）

将指标存储在JSON文件中
简单且易于检查
对于小型到中型部署效果良好
默认存储类型

SQLite（适用于较大规模部署）

将指标存储在SQLite数据库中
对高容量指标有更好的性能
需要better-sqlite3包（自动安装）
如果SQLite不可用，则回退到文件系统

配置选项

选项	描述	默认值
`METRICS_PERSISTENCE_ENABLED`	启用/禁用持久性	`false`
`METRICS_PERSISTENCE_TYPE`	存储类型：`filesystem`或`sqlite`	`filesystem`
`METRICS_PERSISTENCE_PATH`	存储指标的路径（相对或绝对）	`./metrics-storage`
`METRICS_PERSISTENCE_SAVE_INTERVAL_MS`	保存指标的频率（毫秒）	`30000`（30秒）

Docker设置

使用Docker时，请确保将指标存储目录作为卷挂载：

volumes:
  - ./metrics-storage:/app/metrics-storage

这确保即使容器被重建，指标也会保留。

工作原理

启动时：应用程序从存储加载持久性指标，并将其恢复到Prometheus注册表
运行时：指标每30秒自动保存一次（可通过METRICS_PERSISTENCE_SAVE_INTERVAL_MS配置）
关闭时：在进程退出前最后一次保存指标

向后兼容性

指标持久性是可选的 - 默认禁用
如果持久性初始化失败，应用程序将继续运行而没有持久性（记录警告）
没有持久性的现有部署将继续按以前的方式工作

故障排除

指标未持久化：

检查是否设置了METRICS_PERSISTENCE_ENABLED=true
验证存储路径是否可写
检查应用程序日志中的持久性相关错误

权限错误：

确保存储目录存在且可写
在Docker中，验证卷挂载是否正确配置

贡献

欢迎对这个项目做出贡献！无论您想：

🐛 报告bug或问题
💡 提出新功能或改进
🔧 提交修复或增强的PR
📖 改进文档或示例
🧪 添加测试或改进现有测试

开始

分叉仓库
创建功能分支：git checkout -b feature/your-feature-name
进行更改并彻底测试
提交更改：git commit -m "添加您的功能"
推送到您的分叉：git push origin feature/your-feature-name
打开PR

问题或讨论？

我随时愿意讨论问题、审查PR或只是聊聊这个项目！

随时私信我在LinkedIn - 我很乐意听到您的声音并帮助解答任何疑问。

LinkedIn个人资料

编程愉快！🚀