- validate-woodpecker.sh: 全面验证配置文件 - test-step.sh: 单步测试工具，支持 Docker 隔离环境 - README.md: 详细使用文档和最佳实践 这些工具可以在本地验证和测试 CI/CD 配置，避免通过持续提交来测试
This commit is contained in:
张翔
@@ -0,0 +1,264 @@
|
||||
# Woodpecker CI 本地测试工具
|
||||
|
||||
本目录包含用于本地测试和验证 Woodpecker CI 配置的工具。
|
||||
|
||||
## 📁 文件说明
|
||||
|
||||
### 1. `validate-woodpecker.sh` - 配置验证工具
|
||||
|
||||
**功能**：全面验证 `.woodpecker.yml` 配置文件的正确性
|
||||
|
||||
**检查项目**：
|
||||
- ✅ YAML 语法检查
|
||||
- ✅ 必需字段检查（steps, image, commands）
|
||||
- ✅ 镜像格式验证
|
||||
- ✅ 环境变量和 secrets 检查
|
||||
- ✅ when 条件逻辑分析
|
||||
- ✅ 执行顺序模拟
|
||||
|
||||
**使用方法**：
|
||||
```bash
|
||||
./scripts/validate-woodpecker.sh
|
||||
```
|
||||
|
||||
**输出示例**：
|
||||
```
|
||||
==========================================
|
||||
Woodpecker CI 配置本地验证工具
|
||||
==========================================
|
||||
|
||||
✅ 文件存在: .woodpecker.yml
|
||||
|
||||
1️⃣ YAML 语法检查
|
||||
----------------------------------------
|
||||
✅ YAML 语法正确
|
||||
|
||||
2️⃣ 检查必需字段
|
||||
----------------------------------------
|
||||
✅ 步骤 'lint' 有分支条件: ['feature/**', 'dev', 'release', 'release/**']
|
||||
✅ 步骤 'lint' 有事件条件: ['push', 'pull_request']
|
||||
...
|
||||
```
|
||||
|
||||
### 2. `test-step.sh` - 单步测试工具
|
||||
|
||||
**功能**：在本地 Docker 环境中测试单个 pipeline 步骤
|
||||
|
||||
**使用方法**：
|
||||
```bash
|
||||
# 查看可用步骤
|
||||
./scripts/test-step.sh
|
||||
|
||||
# Dry-run 模式（仅显示配置，不执行）
|
||||
./scripts/test-step.sh notify-wechat-success --dry-run
|
||||
|
||||
# 实际执行步骤
|
||||
./scripts/test-step.sh lint
|
||||
```
|
||||
|
||||
**特性**：
|
||||
- 🔍 自动解析步骤配置
|
||||
- 🐳 使用 Docker 隔离环境
|
||||
- 🔐 模拟 Woodpecker CI 环境变量
|
||||
- 📝 显示详细执行信息
|
||||
|
||||
### 3. `test-woodpecker-local.sh` - 本地测试指南
|
||||
|
||||
**功能**：显示 Woodpecker CI 本地测试的方法和命令
|
||||
|
||||
**使用方法**：
|
||||
```bash
|
||||
./scripts/test-woodpecker-local.sh
|
||||
```
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1. 验证配置文件
|
||||
|
||||
在提交代码前，先运行验证工具：
|
||||
|
||||
```bash
|
||||
./scripts/validate-woodpecker.sh
|
||||
```
|
||||
|
||||
如果所有检查都通过，说明配置文件基本正确。
|
||||
|
||||
### 2. 测试单个步骤
|
||||
|
||||
如果某个步骤有问题，可以使用单步测试工具：
|
||||
|
||||
```bash
|
||||
# 先 dry-run 查看配置
|
||||
./scripts/test-step.sh <step_name> --dry-run
|
||||
|
||||
# 确认无误后执行
|
||||
./scripts/test-step.sh <step_name>
|
||||
```
|
||||
|
||||
### 3. 使用 Woodpecker CLI（推荐）
|
||||
|
||||
安装 Woodpecker CLI：
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install woodpecker-cli
|
||||
|
||||
# Linux
|
||||
curl -L https://github.com/woodpecker-ci/woodpecker/releases/latest/download/woodpecker-cli-linux-amd64 -o /usr/local/bin/woodpecker-cli
|
||||
chmod +x /usr/local/bin/woodpecker-cli
|
||||
```
|
||||
|
||||
本地运行整个 pipeline：
|
||||
|
||||
```bash
|
||||
woodpecker-cli exec .woodpecker.yml
|
||||
```
|
||||
|
||||
### 4. 使用 Docker 模拟
|
||||
|
||||
如果没有安装 Woodpecker CLI，可以使用 Docker：
|
||||
|
||||
```bash
|
||||
docker run --rm \
|
||||
-v $(pwd):/woodpecker/src \
|
||||
-w /woodpecker/src \
|
||||
woodpeckerci/woodpecker-cli:latest \
|
||||
exec .woodpecker.yml
|
||||
```
|
||||
|
||||
## 🔧 高级用法
|
||||
|
||||
### 测试特定分支的步骤
|
||||
|
||||
设置环境变量模拟特定分支：
|
||||
|
||||
```bash
|
||||
export CI_COMMIT_BRANCH="release/v1.0.0"
|
||||
./scripts/test-step.sh notify-wechat-success
|
||||
```
|
||||
|
||||
### 测试 secrets
|
||||
|
||||
**注意**：本地测试无法访问 Woodpecker CI 中的 secrets。
|
||||
|
||||
解决方案：
|
||||
1. 创建 `.env` 文件存储测试用的 secrets（**不要提交到 git**）
|
||||
2. 在测试时手动设置环境变量：
|
||||
|
||||
```bash
|
||||
export WECHAT_WEBHOOK="https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY"
|
||||
./scripts/test-step.sh notify-wechat-success
|
||||
```
|
||||
|
||||
### 调试环境变量
|
||||
|
||||
查看步骤会接收到哪些环境变量：
|
||||
|
||||
```bash
|
||||
./scripts/test-step.sh <step_name> --dry-run | grep "环境变量"
|
||||
```
|
||||
|
||||
## 📋 最佳实践
|
||||
|
||||
### 1. 提交前验证
|
||||
|
||||
在每次修改 `.woodpecker.yml` 后，运行：
|
||||
|
||||
```bash
|
||||
./scripts/validate-woodpecker.sh
|
||||
```
|
||||
|
||||
### 2. 逐步测试
|
||||
|
||||
不要一次性测试整个 pipeline，而是：
|
||||
|
||||
1. 先验证配置文件
|
||||
2. 再测试单个步骤
|
||||
3. 最后测试整个 pipeline
|
||||
|
||||
### 3. 使用版本控制
|
||||
|
||||
将测试脚本纳入版本控制：
|
||||
|
||||
```bash
|
||||
git add scripts/
|
||||
git commit -m "feat: 添加 Woodpecker CI 本地测试工具"
|
||||
```
|
||||
|
||||
### 4. 持续改进
|
||||
|
||||
发现新的测试需求时，更新测试脚本：
|
||||
|
||||
```bash
|
||||
# 编辑验证脚本
|
||||
vim scripts/validate-woodpecker.sh
|
||||
|
||||
# 添加新的检查项
|
||||
```
|
||||
|
||||
## 🐛 常见问题
|
||||
|
||||
### Q1: 为什么本地测试成功，但 CI 中失败？
|
||||
|
||||
**可能原因**：
|
||||
1. 环境变量不同（检查 secrets）
|
||||
2. 网络访问限制
|
||||
3. 文件权限问题
|
||||
4. Docker 镜像版本不一致
|
||||
|
||||
**解决方法**：
|
||||
```bash
|
||||
# 对比环境变量
|
||||
./scripts/test-step.sh <step_name> --dry-run
|
||||
|
||||
# 检查 CI 日志中的环境变量
|
||||
# 在 CI 中添加调试命令
|
||||
commands:
|
||||
- env | sort
|
||||
- echo "Branch: $CI_COMMIT_BRANCH"
|
||||
```
|
||||
|
||||
### Q2: 如何测试需要 secrets 的步骤？
|
||||
|
||||
**方法 1**：使用测试用的 secrets
|
||||
```bash
|
||||
export WECHAT_WEBHOOK="https://test.example.com/webhook"
|
||||
./scripts/test-step.sh notify-wechat-success
|
||||
```
|
||||
|
||||
**方法 2**：跳过 secrets 检查
|
||||
```bash
|
||||
# 修改步骤配置，使用环境变量而不是 from_secret
|
||||
```
|
||||
|
||||
### Q3: 如何测试 when 条件？
|
||||
|
||||
**方法**：设置相应的环境变量
|
||||
```bash
|
||||
# 测试 release 分支的步骤
|
||||
export CI_COMMIT_BRANCH="release/v1.0.0"
|
||||
./scripts/test-step.sh deploy-production --dry-run
|
||||
|
||||
# 测试 feature 分支的步骤
|
||||
export CI_COMMIT_BRANCH="feature/new-feature"
|
||||
./scripts/test-step.sh e2e-smoke --dry-run
|
||||
```
|
||||
|
||||
## 📚 相关资源
|
||||
|
||||
- [Woodpecker CI 官方文档](https://woodpecker-ci.org/docs/intro)
|
||||
- [Woodpecker CLI 文档](https://woodpecker-ci.org/docs/cli)
|
||||
- [Woodpecker 配置参考](https://woodpecker-ci.org/docs/usage/pipeline-syntax)
|
||||
|
||||
## 🤝 贡献
|
||||
|
||||
如果你发现新的测试需求或改进点，欢迎更新这些脚本：
|
||||
|
||||
1. Fork 项目
|
||||
2. 创建特性分支
|
||||
3. 提交改进
|
||||
4. 创建 Pull Request
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
这些测试工具遵循项目的主许可证。
|
||||
Reference in New Issue
Block a user