Woodpecker CI 工作流语法详解

Woodpecker CI 工作流语法详解

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

作为一款轻量级的持续集成工具，Woodpecker CI 通过简洁的 YAML 语法定义工作流，实现自动化构建、测试和部署。本文将深入解析 Woodpecker 的工作流语法，帮助开发者高效配置 CI/CD 流程。

工作流基础概念

Woodpecker 的工作流由一系列步骤(step)组成，这些步骤默认按顺序执行。当某个步骤返回非零退出码时，整个工作流会立即终止并标记为失败状态。

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

步骤命名规则

步骤名称(name)是可选的，如果未指定，系统会自动编号。也可以使用字典形式定义步骤：

steps:
  后端构建:
    image: golang
    commands:
      - go build
      - go test

跳过特定提交

在提交消息中包含 [SKIP CI] 或 [CI SKIP]（不区分大小写）可以跳过该提交的构建：

git commit -m "更新文档 [CI SKIP]"

步骤配置详解

镜像(image)配置

每个步骤在指定容器中执行命令，image 定义使用的容器镜像：

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

支持多种镜像格式：

• golang (默认使用最新版)
• golang:1.18 (指定版本)
• library/golang:1.18 (完整仓库路径)

拉取策略(pull)

默认只在镜像不存在时拉取，设置 pull: true 强制拉取最新镜像：

steps:
  - name: 构建
    image: golang:latest
    pull: true

命令(commands)

步骤中的命令会按顺序执行，Woodpecker 会将其转换为 shell 脚本：

commands:
  - go build
  - go test

等效于：

#!/bin/sh
set -e

go build
go test

入口点(entrypoint)

可以自定义容器入口点，必须是命令和参数的列表：

entrypoint: ["/bin/sh", "-c"]

环境变量(environment)

支持为每个步骤设置独立的环境变量：

environment:
  GO_VERSION: 1.18
  NODE_ENV: production

失败处理(failure)

设置 failure: ignore 允许步骤失败而不影响整个工作流：

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

条件执行(when)

通过 when 块可以定义步骤执行条件：

仓库条件(repo)

when:
  - repo: myorg/myrepo

分支条件(branch)

when:
  - branch: main

支持通配符和排除规则：

when:
  - branch:
      include: [main, feature/*]
      exclude: [feature/experimental]

事件类型(event)

支持多种事件类型：

• push: 分支推送
• pull_request: PR 创建或更新
• tag: 标签推送
• cron: 定时任务
• manual: 手动触发

when:
  - event: [push, pull_request]

路径变更(path)

仅当指定路径文件变更时执行：

when:
  - path: 'src/**/*.go'

自定义条件(evaluate)

使用表达式定义复杂条件：

when:
  - evaluate: 'CI_COMMIT_BRANCH == "main" && CI_PIPELINE_EVENT == "push"'

依赖管理(depends_on)

默认步骤顺序执行，使用 depends_on 可定义并行执行关系：

steps:
  - name: 构建
    image: golang
    commands:
      - go build
      
  - name: 测试
    image: golang
    commands:
      - go test
    depends_on: [构建]

工作区(workspace)

定义共享的工作目录：

workspace:
  base: /go
  path: src/github.com/myorg/myrepo

矩阵构建(matrix)

支持多维度并行构建：

matrix:
  GO_VERSION: [1.17, 1.18]
  PLATFORM: [linux/amd64, linux/arm64]

标签选择(labels)

通过标签选择执行代理：

labels:
  os: linux
  arch: amd64

最佳实践建议

1. 镜像选择：尽量使用固定版本标签，避免使用 latest 导致构建不稳定
2. 条件执行：合理使用 when 条件减少不必要的构建步骤
3. 并行优化：通过 depends_on 实现步骤并行执行，缩短构建时间
4. 资源隔离：为不同项目设置独立的工作区路径
5. 错误处理：对非关键步骤设置 failure: ignore

通过灵活组合这些配置选项，可以构建出高效可靠的 CI/CD 流程，满足从简单到复杂的各种自动化需求。

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