企业官网建设流程全解析

• CI/CD
• DevOps

Woodpecker 的 Pipeline 配置（YAML 语法）变更遵循一套严格的弃用（deprecation）流程，以保证用户在语法演进过程中有充足的迁移时间。本文以 3.17 版本文档中记录的弃用策略为骨架，结合仓库源码深入讲解「警告 → 错误 → 代码清理」的三阶段时间线、secrets:→from_secret:的完整迁移实例，以及runs_on、CI_*环境变量等正在执行中的弃用案例，帮助维护者与用户理解并安全穿越每一次破坏性变更。

为什么需要弃用策略

CI/CD 配置是仓库的「活资产」，一个仓库可能同时存在几十条、上百条流水线。如果语法变更立即生效，所有维护者都会在同一时间被迫修改配置，迁移成本极高且容易出错。Woodpecker 通过将配置变更拆分为可感知、可容忍、可执行三个阶段，把「突然的破坏」转化为「有预告的升级」：

• 可感知：新版本先发出 Linter 警告，让用户提前知道旧语法即将失效；
• 可容忍：警告阶段旧语法仍然完全可用，流水线不会中断；
• 可执行：等到下一个大版本，警告升级为错误，此时用户已有充足时间完成迁移。

该策略面向的是 Pipeline 配置（YAML 语法）层面，与数据库迁移、Go API 变更等内部改动相互独立，是用户最容易感知、也最需要提前规划的一类变更。

弃用流程时间线：三个阶段

根据 docs/versioned_docs/version-3.17/92-development/40-deprecations.md，Pipeline 配置变更遵循如下严格流程。

阶段一：小版本 N.x —— 添加弃用警告

• Linter 显示警告（warning）而非错误（error）；
• 旧语法保持可用，流水线正常运行；
• 官方文档同步更新，展示新语法；
• 警告信息中附带迁移指引，告诉用户需要做什么改动。

这一阶段是用户「无痛感知」的关键：不打断构建，但每次运行都能看到提示，形成持续迁移压力。

阶段二：大版本 (N+1).0 —— 警告升级为错误

• Linter 发出错误（error），流水线直接失败；
• 旧语法不再受支持；
• 该破坏性变更被记录在迁移指南（migration guide）中；
• 用户必须更新自己的配置。

这是正式的 breaking change 节点。对 Woodpecker 而言，大版本发布（如 v2.0.0、v3.0.0）都会集中释放一批升级为错误的弃用项，并在 docs/blog/2024-12-28-release-v3.0.0/index.md 这类发布说明中逐一解释理由与迁移步骤。

阶段三：小版本 (N+1).x —— 代码清理

• 移除已弃用的代码路径；
• 简化/重构实现；
• Parser 不再识别旧语法——此时即使想用旧语法，也会在解析阶段直接失败。

这一阶段属于内部实现清理，用户一般无感，但对维护者意味着长期维护负担的解除。

完整示例：secrets: [token]→environment: { TOKEN: { from_secret: token } }

旧语法：secrets: [token]

新语法：environment: { TOKEN: { from_secret: token } }

这个实例完整展示了从「警告」到「破坏」再到「清理」的全过程，也解释了为什么 Woodpecker 2.x 用户有整整一个主版本周期（约两个小版本系列）的时间来迁移。

实现清单（Implementation Checklist）

当需要弃用一种 Pipeline 配置语法时，维护者需要确保完成以下工作：

• 在/pipeline/frontend/yaml/linter/添加 Linter 警告
• 更新/pipeline/frontend/yaml/linter/schema中的 JSON Schema
• 为弃用语法添加测试用例
• 更新文档，展示新语法

这一清单同时是用户理解「弃用是如何被检测的」的窗口：弃用检测并不是硬编码在编译器里的特殊逻辑，而是 Linter 与 Schema 体系的一部分。

源码视角：弃用检测在 Linter 中如何落地

弃用策略在仓库中的实现主体位于 pipeline/frontend/yaml/linter/linter.go。Linter 在每次 lint 时按顺序执行多项检查，其中与弃用直接相关的有两处：

if err := l.lintSchema(config); err != nil { ... } // JSON Schema 校验 if err := l.lintDeprecations(config); err != nil { ... } // 弃用检查

lintDeprecations的核心逻辑（见 linter.go）会重新解析原始配置，然后逐一匹配已知的弃用模式：

• 检测runs_on字段的使用；
• 遍历deprecatedEnvVars列表，用正则匹配配置中出现的已弃用环境变量引用。

所有弃用警告统一通过pipeline_errors.PipelineError返回，其类型为PipelineErrorTypeDeprecation，且IsWarning: true（见 pipeline/errors/pipeline.go）。每个警告还携带DeprecationErrorData结构体，包含File、Field与指向官方文档的Docs链接（见 pipeline/errors/linter.go），方便用户在 UI 中直接跳转阅读迁移说明。

runs_on的弃用警告

lintDeprecations中第一个检测项是runs_on：

if len(parsed.RunsOn) > 0 { //nolint:staticcheck err = multierr.Append(err, &pipeline_errors.PipelineError{ Type: pipeline_errors.PipelineErrorTypeDeprecation, IsWarning: true, Message: "Usage of `runs_on` is deprecated, use `when.status`", ... }) }

从源码注释（//nolint:staticcheck）可以推断，runs_on字段本身已进入「保留解析但不再推荐使用」的状态，对应的替代方案是when.status条件过滤。

弃用环境变量的正则检测

deprecatedEnvVars列表维护着仍以别名形式注入、但已被替换的环境变量：

var deprecatedEnvVars = []struct { old string replacement string re *regexp.Regexp }{ {"CI_COMMIT_PRERELEASE", "CI_PIPELINE_RELEASE_PRE", deprecatedEnvVarRefRegexp("CI_COMMIT_PRERELEASE")}, {"CI_COMMIT_AUTHOR_AVATAR", "CI_PIPELINE_AVATAR", deprecatedEnvVarRefRegexp("CI_COMMIT_AUTHOR_AVATAR")}, {"CI_PREV_COMMIT_AUTHOR_AVATAR", "CI_PREV_PIPELINE_AVATAR", deprecatedEnvVarRefRegexp("CI_PREV_COMMIT_AUTHOR_AVATAR")}, }

检测用的正则由deprecatedEnvVarRefRegexp生成，覆盖三种引用形式：$NAME、$$NAME与${NAME}，并通过词边界避免误匹配CI_COMMIT_PRERELEASE_FOO这类更长的变量名：

func deprecatedEnvVarRefRegexp(name string) *regexp.Regexp { q := regexp.QuoteMeta(name) return regexp.MustCompile(`\$\{` + q + `\}|\$\$?` + q + `\b`) }

源码注释还标注了明确的升级路线：「下一个大版本将把这条警告升级为失败的 lint 错误（IsWarning: false），再下一个大版本移除这些环境变量本身」——这正是三阶段策略在代码中的直接体现。对应的环境变量替换关系也可以在 docs/versioned_docs/version-3.17/20-usage/50-environment.md 的环境变量表中找到，例如CI_COMMIT_PRERELEASE已标注为deprecated，请改用CI_PIPELINE_RELEASE_PRE。

测试如何锁定弃用行为

pipeline/frontend/yaml/linter/linter_test.go 中的TestDeprecations用表格驱动的方式验证了弃用检测的边界行为：

• $CI_COMMIT_PRERELEASE、$$CI_COMMIT_PRERELEASE、${CI_COMMIT_PRERELEASE}三种写法都会触发对应警告；
• 使用新变量名（如$CI_PIPELINE_RELEASE_PRE）不会触发警告；
• 引用更长变量名（如$CI_COMMIT_PRERELEASE_FOO）不会误报；
• $CI_PREV_COMMIT_AUTHOR_AVATAR只会触发其自身的弃用警告，不会连带触发CI_COMMIT_AUTHOR_AVATAR的警告。

这些用例保证了「旧语法可感知、新语法零噪音、误报最小化」，是弃用策略质量的第一道防线。

用户视角：如何发现与应对弃用警告

在 UI 中查看

Woodpecker 会自动对工作流文件执行 lint，检查错误（errors）、弃用（deprecations）和不良习惯（bad habits），结果会直接显示在任何流水线的 UI 中（见 docs/versioned_docs/version-3.17/20-usage/72-linter.md）。弃用警告（warning）不会阻断流水线，但会在界面上持续提示，直到配置更新。

在 CLI 中手动校验

迁移前可以先在本地批量校验配置文件，而不必依赖服务器：

woodpecker-cli lint <workflow files>

该命令的实现位于 cli/lint/lint.go，支持对单个文件或整个目录进行 lint。建议在升级大版本之前，对所有仓库运行一次该命令，把全部弃用警告一次性找出来，制定迁移清单。

官方迁移指南

每个大版本发布时，破坏性变更都会被汇总到迁移指南（migration guide）中，并在发布说明里详细解释每一项变更的理由与迁移步骤。以 v3.0.0 为例，发布说明 明确指出 v3.0.0 包含大量需要用户更新 pipeline 定义的变更，其中很大一部分是为了摆脱过时的 Drone 定义，并强调「每一项修改都经过仔细考虑与讨论，每个决定背后都有具体理由」。

实战迁移案例：secrets:到from_secret:

这是弃用策略最具代表性的实战案例，也完整对应本文开头的时间线示例。

背景

secrets:关键字在 v2.5.0 起被标记弃用，最终在 v3.0.0 被替换为更灵活、更安全的from_secret:语法。官方发布说明（docs/blog/2024-12-28-release-v3.0.0/index.md）解释了替换的动机：

• 更灵活：源 secret 与目标环境变量可以使用不同的名字；
• 更安全：通过统一的引擎进行内部 secret 解析，防止意外泄露；
• 消除歧义：旧语法中secrets:本质只是简单的环境变量，容易与environment:产生混淆；新语法将两者统一到environment:之下。

迁移前后对比

旧语法（v2.5.0 之前，v3.0.0 之后失效）：

steps: build: image: alpine commands: - echo "The secret is $TOKEN" secrets: [token]

新语法（v2.5.0 起可用，v3.0.0 起强制）：

steps: build: image: alpine commands: - echo "The secret is $TOKEN_ENV" environment: TOKEN_ENV: from_secret: SECRET_TOKEN

注意新语法中目标环境变量TOKEN_ENV与源 secretSECRET_TOKEN名称可以不同，这正是from_secret相比secrets:的核心增强点。

迁移建议时间表

结合时间线示例，给用户的实操建议如下：

常见问题

弃用警告会导致流水线失败吗？不会。弃用警告（IsWarning: true）只提示、不阻断；只有升级为错误（IsWarning: false）后才会导致流水线失败。当前源码中的runs_on与环境变量弃用仍处于警告阶段。

警告什么时候会变成错误？按策略，下一个大版本（如 v4.0.0）发布时，现有警告会统一升级为错误。源码注释已明确标注了这一计划。

为什么有的旧语法在下一个大版本的后续小版本中才被彻底移除？这是刻意设计的「缓冲」。大版本先把警告升级为错误、让用户完成强制迁移；随后的一个小版本再做代码清理、移除旧解析路径，避免「大版本发布 + 代码重构」同时发生带来的风险。

配置里没写runs_on也会收到警告吗？不会。弃用检测基于正则与字段解析，只针对实际出现的旧语法模式；新语法（如when.status、新环境变量名）不会触发任何警告，相关行为已被 linter_test.go 的测试用例明确锁定。

总结

Woodpecker 的弃用策略本质上是一条「先警告、后报错、再清理」的三阶段安全通道：小版本 N.x 让用户无痛感知并迁移，大版本 (N+1).0 强制执行，小版本 (N+1).x 完成代码清理。对用户而言，最务实的做法是：每次大版本发布前，用woodpecker-cli lint批量扫描仓库、逐一消除弃用警告，并在迁移指南与发布说明的指引下完成语法升级——这样就能始终走在破坏性变更之前，而不是被动承受它。

• CI/CD
• DevOps