Woodpecker 本地流水线执行：woodpecker-cli exec 的完整实战指南（v3.17）

• CI/CD
• DevOps

woodpecker-cli exec是 Woodpecker CI/CD 引擎提供的本地流水线执行工具，它可以直接在你本地的仓库检出目录中运行 workflow 文件，无需等待服务器调度。本指南以 v3.17 文档为基础，结合仓库源码（cli/exec、pipeline/backend）深入讲解 exec 的三种典型应用场景、后端引擎选择、metadata 与 secrets 注入机制，以及底层执行原理，帮助你掌握一套「推送前测试、本地调试、离线重放」的完整工作流。

exec 是什么：本地执行流水线的三种典型场景

根据 73-local-execution.md 的定位，woodpecker-cli exec用于「从本地检出目录运行 workflow 文件」，典型场景包括：

1. 推送前测试 pipeline 改动：在提交并触发服务器构建之前，先本地验证.woodpecker/中的 workflow 语法与逻辑是否正确，避免把坏配置推到远端反复触发失败构建；
2. 调试 workflow：无需等待服务器排队或分配 agent，直接在本地复现、观察和修正步骤行为，配合逐行日志快速定位问题；
3. 重放服务器流水线：从 Woodpecker UI 下载某次真实构建的 metadata，用--metadata-file将同一份 workflow 在本地按相同条件重新执行一遍，用于复现线上失败。

从命令注册代码（cli/exec/exec.go#L52-L58）可以看到，exec命令的描述正是execute a local pipeline，其参数约定为[path/to/.woodpecker.yaml]，并且把后端引擎相关的 flags（docker.Flags、kubernetes.Flags、local.Flags）一并拼接到命令上，这意味着 exec 的后端行为与 agent 端高度一致。

前置要求：安装 CLI 并确认后端可用

运行 exec 之前需要满足三个前提：

• 安装woodpecker-cli：可以从发行版软件包或 release 压缩包获取。DEB / RPM 软件包面向linux/amd64与linux/arm64，其他架构需使用二进制 tarball 或容器镜像（参见 Supported platforms）。
• 在仓库检出目录中运行，或通过--repo-path显式指定仓库位置；
• 确保所选后端在本地可用：Docker 后端需要能够访问 Docker daemon；local 后端直接在宿主机上执行命令，不会复现容器镜像环境（例如镜像中预装的环境变量、工作目录布局等不会生效）。

工作区（workspace）的自动推导

如果不传--repo-path，exec 会依据 workflow 文件的位置自动确定仓库根目录，逻辑见 cli/exec/exec.go#L104-L118 的repoRootFromFile：

• 若文件位于.woodpecker/多 workflow 目录内，则以父目录作为工作区（源码会打印auto detected workflow in multi workflow setup, parent directory is used as workspace）；
• 若文件是仓库根目录的单个配置文件（如.woodpecker.yml），则以文件所在目录作为工作区；
• 其余情况以文件自身所在目录为准。

这一推导行为有对应单元测试验证（cli/exec/exec_test.go#L104-L125），分别覆盖了myrepo/.woodpecker/securityscan.yaml、根目录.woodpecker.yml与任意ci.yaml三种布局。

后端的可用性探测

后端选择的底层实现位于 pipeline/backend/backend.go#L24-L41 的FindBackend：当backend-engine为auto-detect（默认值）时，会依次调用每个后端的IsAvailable检查，返回第一个可用的引擎，若全部不可用则报错can't detect an available backend engine。

• Docker 后端（pipeline/backend/docker/docker.go#L75-L83）：当显式设置了--backend-docker-host，或检测到/var/run/docker.sock存在时视为可用；
• local 后端（pipeline/backend/local/local.go#L70-L78）：仅当不在容器内（未设置WOODPECKER_IN_CONTAINER）时可用，显式指定时则直接信任。

快速开始：运行单个 workflow 文件或整个目录

创建或编辑 workflow 文件后，直接执行：

woodpecker-cli exec .woodpecker/my-first-workflow.yaml

也可以传入一个 workflow 目录，exec 会遍历目录下所有.yaml与.yml文件并逐一执行（对应 cli/exec/exec.go#L71-L102 的execDir，通过filepath.Walk收集文件）：

woodpecker-cli exec .woodpecker/

若不传任何参数，exec 会按shared/constant中定义的默认配置优先级自动探测（shared/constant/constant.go#L21-L25）：先找.woodpecker/目录，再依次找.woodpecker.yaml、.woodpecker.yml文件（实现见 cli/common/pipeline.go#L28-L39 的DetectPipelineConfig）。此外还支持一次传入多个路径，每个参数（文件或目录）会被逐个执行（cli/common/pipeline.go#L41-L77）。

默认情况下 Woodpecker 自动探测后端。当需要让本地运行结果与某个特定 agent 后端保持一致时，可以显式指定：

woodpecker-cli exec --backend-engine docker .woodpecker/my-first-workflow.yaml woodpecker-cli exec --backend-engine local .woodpecker/my-first-workflow.yaml

后端引擎的选择：docker、local 与 kubernetes

从 cli/exec/exec.go#L60-L64 的注册列表可以看到，exec 支持三种后端：kubernetes.New()、docker.New()、local.New()。选择哪种取决于你希望本地运行多贴近服务器环境：

• docker 后端：与 agent 端行为最一致，步骤在容器内运行，复现镜像环境，适合验证「推送后服务器上会怎样」。代价是需要本地 Docker daemon，且首次运行需要拉取镜像；
• local 后端：直接在宿主机执行命令，无需任何 daemon，启动最快，适合快速调试脚本逻辑。但镜像环境不会被复现（镜像声明的默认命令、环境变量、ENTRYPOINT等均不会生效），因此结果可能与服务器存在差异；
• kubernetes 后端：面向以 Kubernetes 为后端引擎的用户，本地 exec 同样可以选用，前提是本地具备可用的集群上下文。

值得注意的一个实现细节：当使用 local 后端时，exec 会把repoPath写入全局变量local.CLIWorkaroundExecAtDir（cli/exec/exec.go#L138-L142），local 后端在创建 workflow 环境时据此直接把当前仓库目录作为工作区运行，而不是复制到临时目录（见 pipeline/backend/local/local.go#L56-L57 的注释To handle edge case for running local backend via cli exec）。

注入 metadata：模拟分支、PR、Tag 与事件

workflow 中大量when条件与CI_*环境变量依赖 pipeline metadata。exec 会为每次运行自动生成一份 metadata，同时也允许你用命令行参数覆盖其中任意值，从而测试「某个 PR」「某个 tag」「某个事件」下的分支逻辑：

woodpecker-cli exec \ --pipeline-event push \ --commit-branch main \ --commit-sha "$(git rev-parse HEAD)" \ --repo octocat/hello-world \ .woodpecker/my-first-workflow.yaml

如果从 Woodpecker UI 下载了真实流水线的 metadata，可以配合--metadata-file使用，并用其他 flag 微调个别值：

woodpecker-cli exec \ --metadata-file pipeline-metadata.json \ --pipeline-event pull_request \ .woodpecker/my-first-workflow.yaml

重要警告：metadata 文件不是一个稳定、可移植的 API。其格式只保证在同一服务器与 CLI 版本之间有效。请用它配合匹配版本重放流水线，升级版本后应重新下载，而不是复用旧文件。

metadata 的底层构建逻辑

metadata 的组装位于 cli/exec/metadata.go#L33-L159 的metadataFromContext，值得了解的关键点：

• 若指定了--metadata-file，先读取该 JSON 文件作为 baseline（json.NewDecoder解码）；
• 随后通过metadataFileAndOverrideOrDefault应用各 flag：仅在 metadata 文件未被设置、或该 flag 被显式传入时才覆盖对应字段（cli/exec/metadata.go#L162-L166），这保证了「文件打底、flag 微调」的语义；
• --repo octocat/hello-world会被拆分为Repo.Owner = octocat与Repo.Name = hello-world，进而推导出CI_REPO、CI_REPO_NAME、CI_REPO_OWNER等环境变量；
• --pipeline-changed-files支持两种格式：以[开头的 JSON 数组，或逗号分隔的字符串列表；
• 未显式设置平台时，system-platform默认为runtime.GOOS + "/" + runtime.GOARCH（如linux/amd64）。

常用 metadata flag 的默认值（来自 cli/exec/flags.go）包括：--pipeline-event默认manual、--commit-branch默认main、--repo-default-branch默认main、--system-name默认woodpecker。此外还提供--commit-message、--commit-author-name、--commit-ref、--commit-refspec、--commit-pull-labels、--commit-pull-draft、--pipeline-deploy-to、--prev-*系列（用于模拟上一次流水线状态，配合when: status: ...或CI_PREV_*条件）等大量可覆盖项，完整清单见文末 CLI 参考链接。

注入环境变量与 Secrets

普通环境变量

用可重复的--env传入普通环境变量（底层按key=value切分并合并进 pipeline 环境，见 cli/exec/exec.go#L163-L168）：

woodpecker-cli exec \ --env GOFLAGS=-mod=readonly \ .woodpecker/test.yaml

Secrets：从命令行或本地文件传入

Secrets 不会从服务器下载。本地调试所需的敏感值必须显式提供，一种方式是--secrets：

woodpecker-cli exec \ --secrets deploy_token="$DEPLOY_TOKEN" \ .woodpecker/deploy.yaml

多个 secrets 时，建议放在一个被 Git 忽略的本地 YAML 文件中：

deploy_token: ghp_example registry_password: example-password

woodpecker-cli exec \ --secrets-file .woodpecker/local-secrets.yaml \ .woodpecker/deploy.yaml

源码层面的处理见 cli/exec/exec.go#L144-L161：--secrets（StringMap）与--secrets-file（YAML 解析为map[string]string）收集到的键值对会统一转换为compiler.Secret，并通过compiler.WithSecret注入到编译阶段——这正是服务器端 secrets 注入机制在本地 CLI 中的镜像实现。

高级选项与底层执行机制

超时、终止与退出码

exec的完整 flags 定义在 cli/exec/flags.go，除文档前述内容外，还有以下实用选项：

执行阶段（cli/exec/exec.go#L274-L307）的关键行为：

• 每个 workflow 使用独立的context.WithTimeout（默认 1 小时）运行，并注册 SIGTERM 回调——按Ctrl+C时会打印ctrl+c received, terminating workflow '<name>'并终止当前 workflow；
• 每个 workflow 打印# <workflow-name>作为分隔标题；
• 步骤失败不会作为 runtime error 抛出，但 exec 会通过runtime.Err()检查失败步骤，从而让命令以非零码退出；多个 workflow 的错误通过multierr聚合（cli/exec/exec.go#L294-L306）。

配置校验与日志格式

编译阶段如果 workflow 配置非法，b.Build()会通过lint.FormatLintError输出可读的 lint 错误（cli/exec/exec.go#L252-L259）；如果所有 workflow 都被when条件过滤掉，则报错no workflows to execute (all filtered out)。

步骤日志统一由LineWriter输出到stderr，格式为[步骤名:L行号:N秒] 内容（cli/exec/line.go#L41-L45），例如[build:L0:0s] echo hello。这一格式同样被单元测试锁定：TestExecDummy（cli/exec/exec_test.go#L31-L90）使用 dummy 后端执行一个when: event: manual的最小 workflow，并断言输出行格式与步骤命令内容，验证了「manual 事件默认值 + 日志格式」的整体链路。

更多选项与参考资料

以上是exec的常用选项；全部 flags 的完整清单（含本指南未展开的 metadata 覆盖项、backend 专属选项等）请查阅生成的 CLI 参考文档。

相关的深入学习入口：

• 本地执行官方文档：本指南对应的原始文档；
• cli/exec：exec 命令的核心实现（exec.go、flags.go、metadata.go、line.go）；
• pipeline/backend：后端引擎抽象与FindBackend自动探测逻辑；
• 发行版软件包安装：DEB / RPM 包安装与 systemd 服务配置。

掌握woodpecker-cli exec，意味着你可以在不启动服务器、不占用 agent 的前提下，把「改配置 → 推送 → 等构建 → 看失败」的慢循环压缩成「改配置 → 本地秒级验证 → 再推送」的快循环，配合 metadata 重放能力，本地复现线上问题也不再依赖服务器日志。

• CI/CD
• DevOps