novalon-website/scripts

Woodpecker CI 本地测试工具

本目录包含用于本地测试和验证 Woodpecker CI 配置的工具。

📁 文件说明

1. validate-woodpecker.sh - 配置验证工具

功能：全面验证 .woodpecker.yml 配置文件的正确性

检查项目：

• ✅ YAML 语法检查
• ✅ 必需字段检查（steps, image, commands）
• ✅ 镜像格式验证
• ✅ 环境变量和 secrets 检查
• ✅ when 条件逻辑分析
• ✅ 执行顺序模拟

使用方法：

./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 步骤

使用方法：

# 查看可用步骤
./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 本地测试的方法和命令

使用方法：

./scripts/test-woodpecker-local.sh

🚀 快速开始

1. 验证配置文件

在提交代码前，先运行验证工具：

./scripts/validate-woodpecker.sh

如果所有检查都通过，说明配置文件基本正确。

2. 测试单个步骤

如果某个步骤有问题，可以使用单步测试工具：

# 先 dry-run 查看配置
./scripts/test-step.sh <step_name> --dry-run

# 确认无误后执行
./scripts/test-step.sh <step_name>

3. 使用 Woodpecker CLI（推荐）

安装 Woodpecker CLI：

# 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：

woodpecker-cli exec .woodpecker.yml

4. 使用 Docker 模拟

如果没有安装 Woodpecker CLI，可以使用 Docker：

docker run --rm \
  -v $(pwd):/woodpecker/src \
  -w /woodpecker/src \
  woodpeckerci/woodpecker-cli:latest \
  exec .woodpecker.yml

🔧 高级用法

测试特定分支的步骤

设置环境变量模拟特定分支：

export CI_COMMIT_BRANCH="release/v1.0.0"
./scripts/test-step.sh notify-wechat-success

测试 secrets

注意：本地测试无法访问 Woodpecker CI 中的 secrets。

解决方案：

1. 创建 .env 文件存储测试用的 secrets（不要提交到 git）
2. 在测试时手动设置环境变量：

export WECHAT_WEBHOOK="https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY"
./scripts/test-step.sh notify-wechat-success

调试环境变量

查看步骤会接收到哪些环境变量：

./scripts/test-step.sh <step_name> --dry-run | grep "环境变量"

📋 最佳实践

1. 提交前验证

在每次修改 .woodpecker.yml 后，运行：

./scripts/validate-woodpecker.sh

2. 逐步测试

不要一次性测试整个 pipeline，而是：

1. 先验证配置文件
2. 再测试单个步骤
3. 最后测试整个 pipeline

3. 使用版本控制

将测试脚本纳入版本控制：

git add scripts/
git commit -m "feat: 添加 Woodpecker CI 本地测试工具"

4. 持续改进

发现新的测试需求时，更新测试脚本：

# 编辑验证脚本
vim scripts/validate-woodpecker.sh

# 添加新的检查项

🐛 常见问题

Q1: 为什么本地测试成功，但 CI 中失败？

可能原因：

1. 环境变量不同（检查 secrets）
2. 网络访问限制
3. 文件权限问题
4. Docker 镜像版本不一致

解决方法：

# 对比环境变量
./scripts/test-step.sh <step_name> --dry-run

# 检查 CI 日志中的环境变量
# 在 CI 中添加调试命令
commands:
  - env | sort
  - echo "Branch: $CI_COMMIT_BRANCH"

Q2: 如何测试需要 secrets 的步骤？

方法 1：使用测试用的 secrets

export WECHAT_WEBHOOK="https://test.example.com/webhook"
./scripts/test-step.sh notify-wechat-success

方法 2：跳过 secrets 检查

# 修改步骤配置，使用环境变量而不是 from_secret

Q3: 如何测试 when 条件？

方法：设置相应的环境变量

# 测试 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 官方文档
• Woodpecker CLI 文档
• Woodpecker 配置参考

🤝 贡献

如果你发现新的测试需求或改进点，欢迎更新这些脚本：

1. Fork 项目
2. 创建特性分支
3. 提交改进
4. 创建 Pull Request

📄 许可证

这些测试工具遵循项目的主许可证。