CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载一条 Pipeline 至少包含一个 Workflow工作流而 Workflow 是 Woodpecker 组织 CI/CD 流水线的基本单位。当项目复杂度上升时把构建、测试、Lint、部署拆分成多个 Workflow不仅能显著缩短反馈链路、充分利用多 Agent 并行能力还能让每个环节独立汇报状态。本文以官方文档《Workflows》为主体结合仓库源码系统讲解 Woodpecker 多工作流的目录约定、depends_on依赖编排、optional可选依赖、status失败通知以及concurrency并发限制等核心能力帮助你构建可维护、可扩展的多工作流流水线。什么是 WorkflowWorkflow 是一组按顺序执行的步骤Steps的集合这些步骤共享同一个工作区workspace——即一个包含代码仓库以及前面步骤生成的全部数据的共享文件夹。因此同一个 Workflow 内的多个步骤天然共享文件系统状态而不同 Workflow 之间则完全不共享任何数据。Woodpecker 解析配置文件时有两条基本规则如果仓库根目录下只有一个配置文件.woodpecker.yamlWoodpecker 会创建一个只包含单个 Workflow的 Pipeline如果把配置文件放到默认名为.woodpecker/的目录中Woodpecker 会为目录下的每个文件创建一个独立的 WorkflowWorkflow 的名称就是配置文件的文件名。关于目录解析的细节可以从源码中得到印证。仓库中shared/constant/constant.go定义了默认的配置查找顺序// DefaultConfigOrder represent the priority in which woodpecker searches for a pipeline config by default // folders are indicated by supplying a trailing slash. var DefaultConfigOrder []string{ .woodpecker/, .woodpecker.yaml, .woodpecker.yml, }而server/services/config/forge.go中的getFirstAvailableConfig会按这个顺序依次尝试以/结尾的路径按目录处理调用forge.Dir拉取目录下的文件否则按单个文件处理调用forge.File。目录模式下只有扩展名为.yml或.yaml的文件才会被纳入流水线见filterPipelineFiles这正是文档中只有.yml和.yaml文件会被使用这一约定的底层实现。目录解析的边界规则使用.woodpecker/目录时需要注意以下限制只会解析.yml和.yaml扩展名的文件任何子文件夹中的文件都会被忽略例如.woodpecker/sub-folder/test.yaml不会被当作 Workflow 加载每个文件的文件名不含扩展名就是该 Workflow 的名字用于后续的依赖引用。自定义流水线路径如果不希望使用默认的.woodpecker/目录可以在项目的 Pipeline path流水线路径设置中指定自定义路径例如.my-ci/pipelines/。需要注意要使用多工作流模式自定义路径必须以/结尾这样 Woodpecker 才会把它当作目录来解析。项目设置中该字段的官方说明为The path to the pipeline config file or folder. By default it is left empty which will use the following configuration resolution.woodpecker/*.{yaml,yml}-.woodpecker.yaml-.woodpecker.yml. If you set a custom path Woodpecker tries to load your configuration or fails if no configuration could be found at the specified location. To use a multiple workflows with a custom path you have to change it to a folder path ending with a/like.woodpecker/.详见项目设置文档。使用多工作流的好处把一条大流水线拆分成多个 Workflow主要有三方面收益更快的 Lint/测试反馈Lint 工作流不必等整条流水线跑完就能把状态推送到代码托管平台开发者可以尽早获得反馈更清晰的职责组织可以按关注点拆分流水线——测试、Lint、构建、部署各用一个 Workflow结构一目了然更高的并行度多个 Workflow 可以分派到不同的 Agent 上并行执行整体加速流水线。多工作流示例一个完整的分目录配置下面是一个典型的四工作流项目布局.woodpecker/ ├── build.yaml ├── deploy.yaml ├── lint.yaml └── test.yamlbuild.yaml——负责构建不依赖其他工作流steps: - name: build image: debian:stable-slim commands: - echo building - sleep 5lint.yaml——负责代码检查不依赖其他工作流steps: - name: lint image: debian:stable-slim commands: - echo linting - sleep 5test.yaml——负责测试依赖build完成之后才能开始steps: - name: test image: debian:stable-slim commands: - echo testing - sleep 5 depends_on: - builddeploy.yaml——负责部署必须等lint、build、test三个工作流都成功后才会执行steps: - name: deploy image: debian:stable-slim commands: - echo deploying depends_on: - lint - build - test工作流间不共享文件:::warning 请特别注意文件只在同一个 Workflow 的步骤之间共享参见工作流语法中 File changes are incremental 一节。也就是说你无法在deploy工作流中访问build工作流产生的构建产物。 :::如果确实需要在工作流之间传递产物有两种常见方案使用存储类插件例如把文件上传到 Amazon S3 这类对象存储再在后续工作流中下载重新设计流水线把需要共享产物的步骤合并到同一个 Workflow 中。这一限制的根源在于每个 Workflow 会被编译为独立的流水线任务分派到不同的 Agent 上执行工作区volume只在单个 Workflow 内挂载共享。参见编译器实现pipeline/frontend/yaml/compiler/compiler.go中为每个编译出的配置创建独立默认卷的逻辑。Status Lines每个工作流独立汇报状态每个 Workflow 都会向代码托管平台Forge汇报自己的状态。这意味着你在 PR 或提交上看到的是多个相互独立的检查状态Check Status而不是整条流水线的一个笼统状态——这正好呼应了前面提到的更快的 lint/test 反馈。Flow Control依赖编排与流程控制并行与共享原则多个 Workflow 默认在各自独立的 Agent 上并行运行且相互之间不共享任何数据。这是理解整个 Flow Control 机制的前提。depends_on依赖编排工作流之间的依赖关系通过depends_on元素声明。一个 Workflow 只有在它依赖的所有工作流都成功完成之后才会开始执行。如果某个依赖失败该工作流不会启动。depends_on中每个条目的命名规则是去掉路径、去掉开头的点、去掉.yml/.yaml扩展名后的文件名。例如项目配置目录为.woodpecker/文件名为.woodpecker/.lint.yaml则对应的depends_on条目是lint。为一个已有工作流添加依赖只需要在文件末尾追加depends_on列表steps: - name: deploy image: debian:stable-slim commands: - echo deploying depends_on: - lint - build - test从源码层面看depends_on的解析逻辑位于pipeline/frontend/yaml/constraint/depends_on.go。该实现支持多种书写形式单个字符串、字符串数组、对象数组{name, optional}以及混合数组。每一步的依赖最终在编译器compiler.go中被提取为 DAG有向无环图节点由newDAGCompiler依据depends_on关系生成执行阶段stages。值得注意的是如果依赖的工作流/步骤因为when条件被过滤掉编译器会给出专门的ErrStepFilteredDependency错误提示见compiler.go而非笼统的依赖缺失。status 过滤器失败时也要执行的工作流有些工作流即使流水线失败也必须运行——典型的例子是失败通知。此时需要为该工作流设置status过滤器steps: - name: notify image: debian:stable-slim commands: - echo notifying depends_on: - deploy when: - status: [ success, failure ]它的行为与步骤级的status过滤器完全一致默认情况下只有当依赖全部成功时工作流才会执行而显式声明status: [success, failure]后即使依赖失败工作流也会照常运行执行环境仍会带上失败状态。Optional dependencies可选依赖在 monorepo单仓多项目场景下工作流经常使用when: path让自身只在相关文件变更时运行。此时会碰到一个经典问题deploy工作流希望等待所有检查工作流完成但其中某些检查工作流可能因为路径过滤器不匹配而根本没有被构建。如果使用普通的depends_ondeploy 会被这些不存在的依赖永久阻塞。解决办法是把依赖标记为optional: true只有当被引用的工作流确实存在于本次 Pipeline 中时该依赖才会被强制等待如果依赖没有构建例如其when条件不匹配则会被静默忽略。steps: - name: deploy image: debian:stable-slim commands: - echo deploying app a depends_on: - check-a - name: check-b optional: true - name: check-c optional: true上述示例中deploy总是等待check-acheck-b和check-c只有在它们属于本次 Pipeline 时才被等待被过滤掉则直接跳过。这种必需依赖 可选依赖的组合方式是 monorepo 流水线中最常用的编排模式之一。同样的语法也适用于工作流内部的步骤级依赖如果一个步骤通过depends_on引用另一个步骤并将该依赖标记为optional: true而那个步骤恰好被when条件过滤掉了那么这个依赖也会被静默丢弃。源码实现上Dependency结构体由Name与Optional两个字段组成见depends_on.go并提供RequiredNames()/OptionalNames()辅助方法分别提取必需与可选依赖名depends_on.go。另外IsZero()对 nil 与空切片的区分是有意为之YAML 中显式写了一个空的depends_on非 nil 空切片会被步骤编译器识别为 DAG 模式而完全省略nil则代表顺序执行模式——这是步骤级并行语义的关键信号见depends_on.go。:::info 部分工作流并不需要源码比如失败时的通知任务。可以阅读流水线语法中的skip_clone了解更多。 :::Concurrency限制工作流的并发实例数默认情况下工作流没有并发上限——同一时刻可以任意多个实例同时运行。但某些工作流最典型的是部署工作流必须限制同时运行的数量两个部署同时执行可能引发竞态条件或破坏状态而取消上一个流水线往往也不是好选择因为它可能中断一个正在进行的部署。concurrency设置用于限制同一个工作流同时运行的实例数量。当达到上限时新的实例会保持在队列中直到正在运行的某个实例结束才会启动——不会被取消。steps: - name: deploy image: debian:stable-slim commands: - echo deploying depends_on: - test concurrency: limit: 1也可以使用简写形式只设置 limitconcurrency: 1从源码看Concurrency类型同时支持这两种 YAML 形态标量concurrency: 1只设置Limit映射concurrency: {limit: 1, group: ...}同时设置Limit与Group。解析与序列化实现见pipeline/frontend/yaml/types/concurrency.go其中Limit 0表示禁用限制见IsZero。Ordering同组工作流的排队顺序同一个 group 内排队的工作流按照它们所属 Pipeline 被创建的顺序启动而不是按照它们变为就绪的顺序。这一点在多依赖场景下至关重要即使后创建的 Pipeline 中的检查工作流先完成它的受限工作流也不会插队超越仍在等待的、先创建的 Pipeline。这保证了例如部署总是按提交顺序commit order发生。Groups自定义并发分组默认情况下并发限制按仓库内的每个工作流单独生效同一工作流的不同运行之间互相限制而不同工作流以及其他仓库互不影响。group是可选字段通过设置自定义 group 可以让多个工作流共享同一个限制例如把多个部署类工作流归为一组全局最多同时运行一个或让限制更加精确例如只在某个更细的范围内生效。group 支持环境变量替换因此可以按分支或部署目标来限制并发concurrency: limit: 1 group: deploy-${CI_COMMIT_BRANCH}上面的配置意味着每个分支各自最多同时运行一个部署工作流——分支 A 的部署进行中时分支 B 的部署仍可正常开始。实战建议按关注点拆分至少把lint、test、build、deploy拆成独立文件让 CI 状态粒度更细、反馈更快善用可选依赖在 monorepo 中所有路径过滤的检查类工作流都应声明为optional: true的依赖避免部署被不存在的检查阻塞部署必须限流给部署工作流加上concurrency: {limit: 1, group: deploy-${CI_COMMIT_BRANCH}}既防止并发部署的竞态又保证按提交顺序执行失败通知用 status 过滤器通知类工作流记得声明when: - status: [success, failure]避免失败时静默失联产物跨工作流传递走存储插件不要指望工作流间共享文件系统文件共享只存在于同一工作流的步骤之间。延伸阅读工作流语法Workflow syntax步骤、镜像、when条件、skip_clone等底层语法详解项目设置Project settings自定义流水线路径等仓库级配置环境变量Environment${CI_COMMIT_BRANCH}等内置变量的完整列表插件总览Plugins overview用于跨工作流传递产物的存储类插件源码配置解析入口server/services/config/forge.go、默认配置顺序shared/constant/constant.go、依赖解析pipeline/frontend/yaml/constraint/depends_on.go、并发类型定义pipeline/frontend/yaml/types/concurrency.go、编译器pipeline/frontend/yaml/compiler/compiler.go。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Skill Seekers 自定义工作流Custom Workflows完全指南用 YAML 编排多阶段 AI 增强流水线Skill Seekers 自定义工作流Custom Workflows完全指南用 YAML 编排多阶段 AI 增强流水线 本文面向 Skill Seek人工智能AI 应用AI 技能RAGMCP 服务网页爬虫Pipenv 依赖 Vendoring 机制全解析vendor 目录、补丁工作流与自动更新流水线Pipenv 依赖 Vendoring 机制全解析vendor 目录、补丁工作流与自动更新流水线 导读 Pipenv 将一批第三方 Python 库以ve开发工具CLI包管理器Woodpecker 本地流水线执行指南用 woodpecker-cli exec 调试与回放工作流Woodpecker 本地流水线执行指南用 woodpecker cli exec 调试与回放工作流 woodpecker cli exec 是 WoodpeCI/CDDevOps上一篇ActivityWatch终极免费开源自动时间追踪工具完整指南下一篇Node.js 测试 CI 安全事件全披露TOCTOU 竞态漏洞分析、攻击链复盘与基础设施加固实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
