Woodpecker CI 工作流语法详解：从基础到高级配置

Woodpecker CI 工作流语法详解：从基础到高级配置

woodpecker Woodpecker is a simple CI engine with great extensibility. 项目地址: https://gitcode.com/gh_mirrors/wo/woodpecker

工作流基础概念

Woodpecker CI 的工作流（Workflow）定义了一系列按顺序执行的构建、测试和部署步骤。这些步骤默认会按照 YAML 文件中定义的顺序串行执行，如果某个步骤返回非零退出码，整个工作流会立即终止并返回错误状态。

基本工作流示例

steps:
  - name: 后端构建
    image: golang
    commands:
      - go build
      - go test
  - name: 前端构建
    image: node
    commands:
      - npm install
      - npm run test
      - npm run build

在这个例子中，我们定义了两个步骤："后端构建"和"前端构建"。步骤名称可以任意定义，如果不指定名称，系统会自动为步骤编号。

步骤执行特性

文件变更的持久性

Woodpecker 在流程开始时克隆源代码，所有步骤共享同一个挂载卷，因此文件变更会在步骤间保持：

steps:
  - name: 创建文件
    image: debian
    commands:
      - echo "测试内容" > 我的文件
  - name: 读取文件
    image: debian
    commands:
      - cat 我的文件

镜像配置

每个步骤都在指定的容器镜像中执行命令：

steps:
  - name: 构建
    image: golang:1.18
    pull: true  # 总是拉取最新镜像
    commands:
      - go build

支持任何有效的 Docker 镜像格式：

image: golang
image: golang:1.18
image: library/golang:1.18

命令执行

步骤中的命令会按顺序执行，就像在本地 shell 中一样。Woodpecker 会将命令转换为 shell 脚本执行。

允许失败步骤

某些步骤可以配置为允许失败而不影响整个工作流：

steps:
  - name: 代码检查
    image: golangci/golangci-lint
    commands:
      - golangci-lint run
    failure: ignore

高级条件执行

Woodpecker 提供了强大的条件执行功能，通过 when 块可以定义复杂的执行条件。

基本条件示例

steps:
  - name: 代码格式化检查
    image: woodpeckerci/plugin-prettier
    when:
      - event: pull_request
        repo: myorg/myrepo
      - event: push
        branch: main

条件类型详解

1. 仓库条件：限制特定仓库执行

   when:
     - repo: myorg/myrepo
   

2. 分支条件：限制特定分支执行

   when:
     - branch: main
   

3. 事件条件：根据触发事件执行

   when:
     - event: [push, tag, deployment]
   

4. 路径条件：根据文件变更执行

   when:
     - path: 'src/**'
   

5. 自定义表达式：使用复杂逻辑

   when:
     - evaluate: 'CI_PIPELINE_EVENT == "push" && CI_REPO == "myorg/myrepo"'
   

并行执行与依赖管理

默认情况下步骤是串行执行的，但可以通过 depends_on 实现并行执行和依赖管理：

steps:
  - name: 构建
    image: golang
    commands:
      - go build
      
  - name: 测试
    image: golang
    commands:
      - go test
      
  - name: 部署
    image: woodpeckerci/plugin-kaniko
    depends_on: [构建, 测试]  # 等待构建和测试完成

工作区配置

工作区定义了所有步骤共享的卷和工作目录：

workspace:
  base: /go  # 共享基础目录
  path: src/github.com/myorg/myrepo  # 工作目录

steps:
  - name: 依赖安装
    image: golang:latest
    commands:
      - go get

矩阵构建

Woodpecker 支持矩阵构建，可以针对多种配置并行执行构建：

matrix:
  GO_VERSION: [1.17, 1.18]
  REDIS_VERSION: [6.2, 7.0]

steps:
  - name: 测试
    image: golang:${GO_VERSION}
    commands:
      - go test

标签选择器

可以通过标签选择特定的代理执行工作流：

labels:
  location: asia
  platform: linux/amd64

steps:
  - name: 构建
    image: golang
    commands:
      - go build

最佳实践建议

1. 合理使用条件执行：通过精确的条件限制可以减少不必要的构建步骤
2. 优化并行执行：识别可以并行执行的步骤，提高构建效率
3. 合理配置工作区：确保不同步骤间可以共享必要的文件
4. 使用矩阵构建：针对多版本环境进行全面测试
5. 合理设置标签：确保工作流在合适的代理上执行

通过掌握这些工作流语法特性，您可以构建出高效、灵活的 CI/CD 流程，满足各种复杂的自动化需求。

woodpecker Woodpecker is a simple CI engine with great extensibility. 项目地址: https://gitcode.com/gh_mirrors/wo/woodpecker