企业官网建设流程全解析

• CI/CD
• DevOps

本篇指南以 Woodpecker（一个简单但功能强大的开源 CI/CD 引擎）的官方入门文档为核心，带你走完"激活仓库 → 编写工作流 → 本地验证 → 推送触发 → 插件复用"的完整实战链路。读完本文，你将掌握.woodpecker/工作流文件的编写规范、when条件过滤的用法、woodpecker-cli exec的本地调试方法，以及插件与密钥（secrets）的配置技巧，并了解到这些功能在 Woodpecker 源码中的实际落地方式。

1. 激活仓库（Repository Activation）

在 Woodpecker 中启用一个仓库很简单：进入仓库列表页面，点击New repository，你会看到来自你的代码托管平台（forge，如 GitHub、GitLab、Gitea 等）的仓库列表，用一次点击即可完成激活。

需要特别注意的是：要在 Woodpecker 中启用某个仓库，你必须拥有该仓库的Admin（管理员）权限。原因是 Woodpecker 需要在仓库上添加一个名为webhook（网络钩子）的东西——Woodpecker 依赖它来感知仓库中的各类动作，例如 push（推送）、pull request（合并请求）、tag（标签）等事件，从而触发对应的流水线。

从源码层面看，仓库被激活后，每次 webhook 事件到达服务端，都会走一遍完整的流水线创建流程：server/pipeline/create.go中的Create()会先跳过带 skip 标记的提交，再刷新 forge 令牌、持久化 pipeline 记录、从 forge 拉取配置（configService.Fetch），随后解析、校验并构建流水线条目，最后把任务派发给调度器与 agent。也就是说，"点击激活"只是第一步，真正的执行链路从 webhook 到达才正式开始。

2. 编写第一条工作流

仓库激活后，Woodpecker 会监听仓库的变更。一旦检测到变更，它就会查找流水线配置。因此，请在仓库中创建文件.woodpecker/my-first-workflow.yaml：

when: - event: push branch: main steps: - name: build image: debian commands: - echo "This is the build step" - echo "binary-data-123" > executable - name: a-test-step image: golang:1.16 commands: - echo "Testing ..." - ./executable

我们来逐段拆解这段配置做了什么：

1. 定义了第一个工作流文件my-first-workflow.yaml。当仓库中只有一个.woodpecker.yaml时，Woodpecker 会创建一个只含单个 workflow 的 pipeline；而当配置文件放在.woodpecker/目录下时（如本例），每个.yaml/.yml文件都会成为一个独立命名的 workflow（详见 多工作流文档）。

2. 用when段做了事件过滤——只有当main分支上发生push事件时，这个工作流才会被执行：

   + when: + - event: push + branch: main ...

   这里when是全局工作流级条件：当when块中的所有子条件都满足时，工作流才会被纳入 pipeline，否则整个工作流会被跳过。在源码中，这一逻辑由 constraint/constraint.go 的Constraint.Match()实现——它依次比对事件（Event）、仓库（Repo）、分支（Branch，注意 tag 事件不参与分支过滤）、引用（Ref）、实例（Instance）、平台（Platform）等条件，任一子条件不满足即为 false；而when列表则是"只要其中一条为真就执行"。

3. 定义了两个步骤：build和a-test-step。

步骤按定义顺序串行执行，因此build会先运行，然后才轮到a-test-step。在build步骤中，我们使用debian镜像，生成一个名为executable的"二进制文件"；在a-test-step中，我们改用golang:1.16镜像，直接执行这个executable文件来测试它。

你可以使用你有权访问的任意镜像仓库（如 Docker Hub）中的镜像：

steps: - name: build - image: debian + image: my-company/image-with-aws_cli commands: - aws help

在 Woodpecker 的源码中，steps的每个元素对应 types/container.go 里的Container结构体，其中image、commands、pull、settings、environment、when、depends_on、failure等字段都被显式解析；而整个工作流文件对应 types/workflow.go 的Workflow结构体，包含when、workspace、clone、steps、services、labels、depends_on等顶层字段。由此可见，"工作流 = 顶层配置 + 一串步骤容器"就是 Woodpecker 配置模型的核心骨架。

步骤之间如何共享文件

细心的读者会发现：build步骤里写入的executable，为什么能在a-test-step里被读取？这是因为 Woodpecker 在工作流开始时克隆源码，并且所有步骤挂载的是同一个共享卷（workspace），因此文件变更会跨步骤保留：

steps: - name: build image: debian commands: - echo "test content" > myfile - name: a-test-step image: debian commands: - cat myfile

这为"第一步构建应用、第二步复用构建产物做测试"提供了基础，也是本入门示例能跑通的关键机制。需要留意的是：文件只在同一个工作流的步骤之间共享，不同工作流之间默认不共享任何数据（如需传递产物，要借助存储类插件，例如 S3 插件）。

3. 本地运行工作流（woodpecker-cli exec）

如果你安装了woodpecker-cli且本地具备受支持的后端（backend），可以在推送之前先在本地运行工作流，以检查语法、命令输出与 metadata 条件是否正确：

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

本地执行非常适合在编辑文件时快速验证。在源码层面，这条命令的实现位于 cli/exec/exec.go：

• 它会读取工作流文件（execFile），或扫描整个.woodpecker/目录下所有.yaml/.yml文件（execDir）；
• 自动检测后端：默认按顺序尝试 kubernetes、docker、local，也可以用--backend-engine docker或--backend-engine local显式指定，让本地运行尽量贴近某个 agent 后端；
• 与服务器端一样走builder.PipelineBuilder.Build()流程，包括环境变量替换、YAML 解析、lint 校验（lint.FormatLintError会把解析/校验错误直接打印出来），若全部工作流被when过滤掉，会提示no workflows to execute (all filtered out)；
• 执行结束后若步骤失败，命令会以非零退出码返回。

更完整的本地执行选项（例如--pipeline-event、--commit-branch、--env、--secrets、--secrets-file、--metadata-file等元数据与环境变量覆盖手段）可以查阅 本地流水线执行。简单示例：测试"仅当 push 到 main 时执行"这条when条件，可以这样模拟：

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

4. 推送文件，触发你的第一条 Pipeline

把配置文件推送到仓库后，Woodpecker 就会自动执行你的第一条 pipeline。你可以在 Woodpecker UI 中进入仓库的Pipelines区块查看执行情况（即本文开头第二张图所示）。

你大概已经注意到：在你的步骤之前，还有一个名为clone的步骤。它会在所有步骤之前执行，把仓库克隆到一个名为workspace的目录中，并且该目录在整个工作流的所有步骤里都可用。这正是前面"步骤间文件共享"的基础：第一个步骤可以用源码构建应用，第二个步骤拿到同一份 workspace 后，就能直接使用前面构建出的二进制文件并加以测试。

关于clone步骤，有几点值得深入了解：

• 它是Woodpecker 自动配置的默认步骤，无需你在 YAML 中声明；你可以在工作流中显式定义clone:段来定制它（例如覆盖depth、切换自定义克隆插件），也可以通过skip_clone: true完全跳过克隆。
• 在服务器端，整个触发链路由server/pipeline/create.go的Create()驱动：检测到跳过提交（见下）→ 刷新令牌 → 保存 pipeline → 从 forge 拉取配置 → 持久化配置 → 调用createPipelineItems解析/校验 → 过滤掉空 pipeline → 派发调度与启动。
• 一个实用小技巧：提交信息中包含[SKIP CI]或[CI SKIP]（不区分大小写）即可跳过单个提交的流水线，例如git commit -m "updated README [CI SKIP]"。该逻辑在源码 constraint/skip.go 中由正则\[(?i:ci *skip|skip *ci)\]实现，且只对push与 pull request 类事件生效。

5. 用插件复用常见任务

有些任务每个项目都会遇到——例如部署到 Kubernetes、发送 Slack 通知。这时你可以使用官方及社区维护的插件，也可以自行创建插件。如果想把一个文件发布到 S3 bucket，只需给 pipeline 添加一个 S3 插件步骤：

steps: # ... - name: upload image: woodpeckerci/plugin-s3 settings: bucket: my-bucket-name access_key: a50d28f4dd477bc184fbd10b376de753 secret_key: from_secret: aws_secret_key source: public/**/* target: /target/location

插件的配置都放在settings段中。这些设置项在编译期会被转换成以PLUGIN_为前缀的大写环境变量注入插件容器——例如设置项url会变成PLUGIN_URL，-会转换为_（详见 创建插件）。这一转换正是由源码 compiler/settings/params.go 的ParamsToEnv/sanitizeParamKey完成的。

关于密钥（secrets）：示例中secret_key使用了from_secret: aws_secret_key语法，密钥本身需要在 Woodpecker UI 中预先定义。在编译阶段，params.go 的injectSecret会识别形如{from_secret: name}的 map，并向密钥服务查询真实值注入。密钥分为仓库级、组织级、全局级三个层次，默认不会暴露给 pull_request 事件，还可以通过"插件过滤"限制某个密钥只对特定插件可见，详见 密钥文档。

关于插件的两个要点补充：

• 插件本质上是 pipeline 中的一个步骤，同样共享 workspace 卷；但为安全起见，插件被限制为只能执行作者预定义的功能——插件不能与commands或entrypoint同时使用，否则会报错。这一点在源码中体现为 container.go 的IsPlugin()方法：当容器没有commands、entrypoint且未显式设置environment时，它才被判定为插件。
• 步骤级when：和文件顶部面向整个工作流的when一样，每个步骤也可以有自己的when段，用来精细控制"该步骤在什么条件下执行"（例如只在pull_request事件、或只在main分支推送时执行 prettier 检查）。步骤级与工作流级when共享同一套 constraint 实现，支持event、branch、repo、ref、status、path、evaluate等多种过滤维度。

6. 下一步：深入工作流语法与插件生态

到这里，你已经具备编写并运行第一条 pipeline 的完整能力。接下来可以沿着两个方向深入：

• 工作流语法：全面了解steps的串行/并行控制（depends_on）、services服务容器、workspace自定义、matrix矩阵构建、failure: ignore失败容忍、pull镜像拉取策略、labels标签调度等能力，参考 工作流语法。
• 插件生态：了解插件的定位、隔离机制与查找途径，参考 插件总览；需要自研插件时，可以按 创建插件 的指引，把脚本打包成以 ENTRYPOINT 方式运行的 Docker 镜像即可。

• CI/CD
• DevOps