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

CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载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 文件」典型场景包括推送前测试 pipeline 改动在提交并触发服务器构建之前先本地验证.woodpecker/中的 workflow 语法与逻辑是否正确避免把坏配置推到远端反复触发失败构建调试 workflow无需等待服务器排队或分配 agent直接在本地复现、观察和修正步骤行为配合逐行日志快速定位问题重放服务器流水线从 Woodpecker UI 下载某次真实构建的 metadata用--metadata-file将同一份 workflow 在本地按相同条件重新执行一遍用于复现线上失败。从命令注册代码cli/exec/exec.go#L52-L58可以看到exec命令的描述正是execute a local pipeline其参数约定为[path/to/.woodpecker.yaml]并且把后端引擎相关的 flagsdocker.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 daemonlocal 后端直接在宿主机上执行命令不会复现容器镜像环境例如镜像中预装的环境变量、工作目录布局等不会生效。工作区workspace的自动推导如果不传--repo-pathexec 会依据 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检查返回第一个可用的引擎若全部不可用则报错cant 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.CLIWorkaroundExecAtDircli/exec/exec.go#L138-L142local 后端在创建 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 文件作为 baselinejson.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传入普通环境变量底层按keyvalue切分并合并进 pipeline 环境见 cli/exec/exec.go#L163-L168woodpecker-cli exec \ --env GOFLAGS-modreadonly \ .woodpecker/test.yamlSecrets从命令行或本地文件传入Secrets 不会从服务器下载。本地调试所需的敏感值必须显式提供一种方式是--secretswoodpecker-cli exec \ --secrets deploy_token$DEPLOY_TOKEN \ .woodpecker/deploy.yaml多个 secrets 时建议放在一个被 Git 忽略的本地 YAML 文件中deploy_token: ghp_example registry_password: example-passwordwoodpecker-cli exec \ --secrets-file .woodpecker/local-secrets.yaml \ .woodpecker/deploy.yaml源码层面的处理见 cli/exec/exec.go#L144-L161--secretsStringMap与--secrets-fileYAML 解析为map[string]string收集到的键值对会统一转换为compiler.Secret并通过compiler.WithSecret注入到编译阶段——这正是服务器端 secrets 注入机制在本地 CLI 中的镜像实现。高级选项与底层执行机制超时、终止与退出码exec的完整 flags 定义在 cli/exec/flags.go除文档前述内容外还有以下实用选项Flag环境变量默认值说明--timeoutWOODPECKER_TIMEOUT1h单个 workflow 的执行超时--repo-pathWOODPECKER_REPO_PATH自动推导本地仓库路径--localWOODPECKER_LOCALtrue从本地目录运行--volumesWOODPECKER_VOLUMES—额外挂载的卷可重复--networkWOODPECKER_NETWORKS—外部网络可重复--plugins-privilegedWOODPECKER_PLUGINS_PRIVILEGED—允许插件以 privileged 模式运行--workspace-base/--workspace-pathCI_WORKSPACE_BASE/CI_WORKSPACE_PATH/woodpecker/src容器内工作区布局--netrc-username/--netrc-password/--netrc-machineCI_NETRC_*—注入私有仓库 clone 凭据--backend-no-proxy/--backend-http-proxy/--backend-https-proxyWOODPECKER_BACKEND_*_PROXY等—以NO_PROXY/HTTP_PROXY/HTTPS_PROXY形式传递给步骤--repo-trusted-network/--repo-trusted-volumes/--repo-trusted-securityCI_REPO_TRUSTED_*—模拟仓库的 trusted 权限网络、卷、安全执行阶段cli/exec/exec.go#L274-L307的关键行为每个 workflow 使用独立的context.WithTimeout默认 1 小时运行并注册 SIGTERM 回调——按CtrlC时会打印ctrlc 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。这一格式同样被单元测试锁定TestExecDummycli/exec/exec_test.go#L31-L90使用 dummy 后端执行一个when: event: manual的最小 workflow并断言输出行格式与步骤命令内容验证了「manual 事件默认值 日志格式」的整体链路。更多选项与参考资料以上是exec的常用选项全部 flags 的完整清单含本指南未展开的 metadata 覆盖项、backend 专属选项等请查阅生成的 CLI 参考文档。相关的深入学习入口本地执行官方文档本指南对应的原始文档cli/execexec 命令的核心实现exec.go、flags.go、metadata.go、line.gopipeline/backend后端引擎抽象与FindBackend自动探测逻辑发行版软件包安装DEB / RPM 包安装与 systemd 服务配置。掌握woodpecker-cli exec意味着你可以在不启动服务器、不占用 agent 的前提下把「改配置 → 推送 → 等构建 → 看失败」的慢循环压缩成「改配置 → 本地秒级验证 → 再推送」的快循环配合 metadata 重放能力本地复现线上问题也不再依赖服务器日志。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Woodpecker 本地流水线执行woodpecker-cli exec 实战指南Woodpecker 本地流水线执行woodpecker cli exec 实战指南 woodpecker cli exec 是 Woodpecker CI/CI/CDDevOpsWoodpecker 本地流水线执行指南用 woodpecker-cli exec 调试与回放工作流Woodpecker 本地流水线执行指南用 woodpecker cli exec 调试与回放工作流 woodpecker cli exec 是 WoodpeCI/CDDevOpsWoodpecker CI 流水线步骤实时调试实战sshx 远程终端与 cli exec 本地复现方案Woodpecker CI 流水线步骤实时调试实战sshx 远程终端与 cli exec 本地复现方案 本篇指南基于 Woodpecker 官方社区博客《DeCI/CDDevOps上一篇如何快速掌握LuytenJava反编译的终极指南下一篇AIOX Claude Code 集成详解生命周期 Hooks 全功能体验与完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考