Woodpecker CI 迁移指南：版本升级与配置变更详解

Woodpecker CI 迁移指南：版本升级与配置变更详解

woodpecker Woodpecker is a simple CI engine with great extensibility. 项目地址: https://gitcode.com/gh_mirrors/wo/woodpecker

前言

作为一款持续集成工具，Woodpecker CI 在版本迭代过程中会引入一些配置变更和功能改进。本文将系统梳理各版本间的迁移注意事项，帮助用户顺利完成升级。

核心概念

在开始迁移前，需要了解 Woodpecker CI 的几个核心术语变更：

1. 术语变更：

   • build → pipeline（工作流）
   • job → step（步骤）
   • 相关环境变量前缀也从 CI_BUILD_ 和 CI_JOB_ 变更为 CI_PIPELINE_ 和 CI_STEP_

2. 路径变更：

   • 默认工作空间从 /drone 改为 /woodpecker
   • 数据存储路径从 /var/lib/drone 改为 /var/lib/woodpecker

主要版本迁移指南

从 Drone 迁移至 Woodpecker

前提条件：

• 仅支持从 Drone v0.8 或更低版本迁移
• 必须首先升级到 Woodpecker v0.14.4 完成基础迁移
• 之后再升级到最新版本

关键变更：

1. 所有 DRONE_* 环境变量需替换为 WOODPECKER_* 前缀
2. 数据库位置变更：
   • SQLite 数据库从 drone.sqlite 改为 woodpecker.sqlite
3. Prometheus 指标前缀从 drone_* 改为 woodpecker_*

版本 0.15.0 重要变更

1. 配置文件路径：

   • 默认查找顺序变更为： .woodpecker/*.yml → .woodpecker.yml → .drone.yml
   • 新项目默认为空，按上述顺序查找

2. 镜像标签策略：

   • 引入三种镜像类型：
     • latest：稳定版
     • next：预发布版
     • x.x.x：具体版本号
   • 每种类型都有对应的 Alpine 变体

3. 环境变量清理：

   • 移除了大量冗余的环境变量别名
   • 例如 WOODPECKER_AGENT_SECRET 统一替代了多个旧变量

版本 1.0.0 重大变更

1. 安全增强：

   • 配置扩展的签名机制从共享密钥 HMAC 升级为 ed25519 密钥对

2. API 端点重构：

   • 使用 repo-id 替代 owner/repo 组合
   • 使用 org-id 替代组织名称
   • 新增查找端点用于获取 ID

3. 步骤配置变更：

   • 移除了 command: 字段
   • 必须使用 commands: 并确保镜像入口点兼容

4. 日志迁移：

   • 旧日志格式需要特殊迁移
   • 设置 WOODPECKER_MIGRATIONS_ALLOW_LONG=true 允许长时间迁移

版本 2.0.0 关键变更

1. 环境变量清理：

   • 移除了 CI_BUILD_* 等旧变量
   • 统一使用新命名规范

2. 过滤机制改进：

   • platform: 过滤器改为 labels:
   • 秘密配置中的 event 改为 events，image 改为 images

3. 后端精简：

   • 移除了 ssh 后端，建议使用 local 后端

最新版本 (next) 变更预告

1. 配置弃用：

   • gated 设置改为 require-approval
   • steps.[name].group 改为 depends_on
   • 移除 WOODPECKER_ROOT_PATH 和 WOODPECKER_ROOT_URL

2. 行为变更：

   • 无配置文件的流水线将跳过而非失败
   • 秘密环境变量不再自动转为大写

3. 专家级配置：

   • 使用 WOODPECKER_EXPERT_FORGE_OAUTH_HOST 替代旧变量
   • Webhook 主机配置变量更新

最佳实践建议

1. 升级策略：

   • 始终先升级到中间版本，再逐步升级到目标版本
   • 生产环境建议先在测试环境验证

2. 配置检查：

   • 使用 WOODPECKER_LOG_LEVEL=debug 获取详细日志
   • 检查所有自定义脚本是否依赖了将被移除的变量

3. 回滚准备：

   • 升级前备份数据库和关键配置
   • 记录当前使用的确切版本号

结语

Woodpecker CI 的持续演进带来了更好的性能和安全性，但也需要用户关注版本间的变更。建议定期查看更新日志，规划升级路径。对于关键业务系统，可采用分阶段升级策略，确保平稳过渡。

woodpecker Woodpecker is a simple CI engine with great extensibility. 项目地址: https://gitcode.com/gh_mirrors/wo/woodpecker