跳到主要内容

工作流语法

工作流部分定义了构建、测试和部署代码的步骤列表。这些步骤按照定义的顺序串行执行。如果某个步骤返回非零退出代码，工作流以及整个管道将立即终止并返回错误状态。

备注

此规则的例外是具有 status: [failure] 条件的步骤，这确保它们在运行失败的情况下被执行。

备注

我们支持大部分 YAML 1.2，但为了向后兼容性保留了 1.1 的一些行为。 了解更多：https://github.com/go-yaml/yaml

示例步骤：

steps:
  - name: backend
    image: golang
    commands:
      - go build
      - go test
  - name: frontend
    image: node
    commands:
      - npm install
      - npm run test
      - npm run build

在上面的示例中，我们定义了两个步骤：frontend 和 backend。这些步骤的名称是完全任意的。

名称是可选的，如果不添加，步骤将被编号。

命名步骤的另一种方法是使用字典：

steps:
  backend:
    image: golang
    commands:
      - go build
      - go test
  frontend:
    image: node
    commands:
      - npm install
      - npm run test
      - npm run build

步骤​

每个步骤都在隔离的 Docker 容器中执行。步骤无法访问其他步骤的运行环境，但它们可以通过共享工作空间访问文件系统。

image​

每个步骤都必须指定一个 Docker 镜像。Woodpecker 使用此镜像创建一个容器并执行步骤命令。

steps:
  - name: build
    image: golang:1.19
    commands:
      - go build
      - go test

Woodpecker 支持任何有效的 Docker 镜像，包括官方镜像、自定义镜像和私有注册表中的镜像。

commands​

步骤执行 shell 命令。如果任何命令返回非零退出代码，步骤将失败并终止管道。

steps:
  - name: backend
    image: golang
    commands:
      - go build
      - go test

单个命令也可以分解为多行：

steps:
  - name: backend
    image: golang
    commands:
      - |
        go build
        go test
提示

YAML 提示： 您可以使用 YAML 多行字符串语法，包括折叠标量 > 和字面量标量 |，如上例所示。

environment​

Woodpecker 为每个步骤提供了预定义环境变量的能力，以及定义自定义环境变量的能力。

steps:
  - name: build
    image: golang
    environment:
      - CGO_ENABLED=0
      - GOOS=linux
    commands:
      - go build
      - go test

请注意，环境变量不会在步骤之间共享。

secrets​

Woodpecker 提供了向步骤注入命名密钥的能力。这些密钥可以在 Woodpecker 用户界面中定义，或者通过 Woodpecker 命令行工具定义。

steps:
  - name: build
    image: golang
    secrets: [username, password]
    commands:
      - echo $USERNAME
      - echo $PASSWORD

请注意，密钥名称会自动转换为大写，并作为环境变量提供给您的步骤。

when​

Woodpecker 支持为各个步骤定义一系列条件。如果满足所有条件，步骤将被执行，否则将被跳过。

steps:
  - name: build
    image: golang
    commands:
      - go build
    when:
      - event: push
        branch: main

branch​

示例分支过滤器：

when:
  - branch: main

when:
  - branch: [main, develop]

when:
  - branch:
      include: [main, release/*]
      exclude: [release/1.0.0, release/1.1.*]

event​

示例事件过滤器：

when:
  - event: push

when:
  - event: [push, pull_request]

when:
  - event:
      include: [push, pull_request]
      exclude: tag

tag​

示例标签过滤器：

when:
  - event: tag
    tag: v*

when:
  - event: tag
    tag: [v*, release/*]

status​

示例状态过滤器：

when:
  - status: success

when:
  - status: [success, failure]

执行步骤时：

  • success - 当管道处于成功状态时
  • failure - 当管道处于失败状态时

platform​

示例平台过滤器：

when:
  - platform: linux/amd64

when:
  - platform: [linux/*, windows/amd64]

instance​

示例实例过滤器：

when:
  - instance: stage.woodpecker.company.com

when:
  - instance: [stage.woodpecker.company.com, ci.woodpecker.company.com]

path​

示例路径过滤器：

when:
  - path: "src/*"

when:
  - path: ["src/*", "tests/*"]

when:
  - path:
      include: ["src/*", "tests/*"]
      exclude: ["*.md", "docs/*"]

路径是相对于仓库根目录计算的。

evaluate​

示例评估过滤器：

when:
  - evaluate: 'CI_COMMIT_AUTHOR_EMAIL == "octocat@github.com"'
注意

评估表达式在服务器上运行，而不是在代理上运行，因此只能访问内置环境变量和全局定义的密钥。

failure​

某些步骤，如通知或清理任务，可能需要在管道失败后运行。使用 failure 属性来执行这样的步骤：

steps:
  - name: cleanup
    image: golang
    commands:
      - make cleanup
    failure: ignore

服务​

Woodpecker 可以为您的管道提供服务容器。典型的用例是运行数据库或缓存服务。

services:
  - name: database
    image: mysql
    environment:
      - MYSQL_DATABASE=test

steps:
  - name: test
    image: golang
    commands:
      - go test

服务容器通常会公开端口。要访问服务，您只需使用服务容器的名称作为主机名。在上面的示例中，mysql 服务可以通过主机名 database 访问。

服务配置​

服务容器接受与步骤容器相同的配置参数。

services:
  - name: database
    image: mysql
    environment:
      - MYSQL_DATABASE=test
    commands:
      - mysqld --character-set-server=utf8mb4

服务检测​

如果您需要等待服务完全启动，您可以使用 dockerize 实用程序：

services:
  - name: database
    image: mysql
    environment:
      - MYSQL_DATABASE=test

steps:
  - name: test
    image: golang
    commands:
      - dockerize -wait tcp://database:3306 -timeout 1m
      - go test

服务变量​

Woodpecker 自动为每个服务容器设置环境变量，以便于发现和连接：

services:
  - name: database
    image: mysql

steps:
  - name: test
    image: golang
    commands:
      - echo $DATABASE_PORT_3306_TCP_ADDR
      - echo $DATABASE_PORT_3306_TCP_PORT

管道配置​

when​

Woodpecker 支持为整个管道定义一系列条件。如果满足所有条件，管道将被执行，否则将被跳过。

when:
  - event: push
    branch: main

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

depends_on​

Woodpecker 支持使用 depends_on 属性定义管道依赖关系：

depends_on:
  - lint
  - test

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

runs_on​

使用 runs_on 来指定管道应该在哪些代理上运行：

runs_on: [linux/amd64, my-custom-label]

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

skip_clone​

默认情况下，Woodpecker 会自动配置并执行克隆步骤。您可以手动配置克隆步骤或完全禁用它：

skip_clone: true

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

clone​

使用 clone 部分覆盖默认的克隆配置：

clone:
  git:
    image: woodpeckerci/plugin-git

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

workspace​

工作空间定义了您的源代码的共享卷和工作目录。默认工作空间与您的仓库名称匹配。

workspace:
  path: /go/src/github.com/octocat/hello-world

steps:
  - name: build
    image: golang:latest
    commands:
      - go get
      - go test

工作空间必须是绝对路径。