悟空信创平台帮助文档
  • 跳过提交
  • 步骤
    • 文件更改是增量的
    • image
    • commands
    • environment
    • secrets
    • failure
    • when - 条件行执
    • group - 并行执行
    • volumes
    • detach
    • directory
  • services
  • workspace
  • matrix
  • platform
  • labels
  • variables
  • clone
    • Git子模块
  • skip_clone
  • when - 全局流水线状况
    • repo
    • branch
    • event
    • tag
    • environment
    • instance
    • path
  • depends_on
  • Privileged mode

流水线语法

流水线部分定义了生成、测试和部署代码的步骤列表.流水线步骤按定义顺序串行执行.如果步骤返回非零退出代码,流水线将立即中止并返回失败状态.

示例流水线:

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

在上面的例子中,我们定义了两个流水线步骤,frontend 和 backend这些步骤的名称完全是任意的.

命名步骤的另一种方法是使用 name 关键字:

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

请记住,名称是可选的,如果未添加,则将对步骤进行编号.

跳过提交

悟空通过添加到提交消息来跳过单个提交.请注意,这不区分大小写.

git commit -m "updated README [CI SKIP]"

步骤

流水线的每个步骤都在指定的容器内执行任意命令.定义的命令以串行方式执行. 当前流水线运行的关联提交使用 git 签出到工作区,该工作区作为工作目录挂载到流水线的每个步骤.

 pipeline:
   backend:
     image: golang
     commands:
+      - go build
+      - go test

文件更改是增量的

  • 悟空在开始流水线中克隆源代码
  • 对文件的更改将通过步骤保留,因为同一卷将装载到所有步骤
# .woodpecker.yml
pipeline:
  build:
    image: debian
    commands:
      - echo "test content" > myfile
  a-test-step:
    image: debian
    commands:
      - cat myfile

image

悟空拉取定义的镜像并将其用作环境来执行流水线步骤命令,用于插件和服务容器.

当使用local后端时,image条目用于指定用于运行命令的shell,如Bash或Fish.

 pipeline:
   build:
+    image: golang:1.6
     commands:
       - go build
       - go test

   publish:
+    image: plugins/docker
     repo: foo/bar

 services:
   database:
+    image: mysql

悟空支持来自任何 Docker 注册表的任何有效 Docker 镜像:

image: golang
image: golang:1.7
image: library/golang:1.7
image: index.docker.io/library/golang
image: index.docker.io/library/golang:1.7

悟空不会自动升级容器镜像.在更新可用时始终拉取最新镜像的示例配置:

 pipeline:
   build:
     image: golang:latest
+    pull: true
来自私有注册表的镜像

必须在 UI 上提供注册表凭据,才能拉取 YAML 配置文件中定义的专用流水线镜像.

这些凭据永远不会向流水线公开,这意味着它们不能用于推送,并且可以安全地用于拉取请求.推送到注册表仍然需要为相应的插件设置凭据.

使用私有镜像的配置示例:

 pipeline:
   build:
+    image: gcr.io/custom/golang
     commands:
       - go build
       - go test

悟空将注册表主机名与 YAML 中的每个镜像匹配.如果主机名匹配,则注册表凭据用于向注册表进行身份验证并拉取镜像.请注意,注册表凭据由悟空代理使用,并且永远不会向生成容器公开.

注册表主机名示例:

  • 镜像gcr.io/foo/bar有gcr.io主机名
  • 镜像foo/bar有docker.io主机名
  • 镜像qux.com:8000/foo/bar有qux.com:8000主机名

注册表主机名匹配逻辑示例:

  • 主机名gcr.io匹配镜像gcr.io/foo/bar
  • 主机名docker.io 匹配 golang
  • 主机名 docker.io 匹配 library/golang
  • 主机名 docker.io 匹配 bradyrydzewski/golang
  • 主机名 docker.io 匹配 bradyrydzewski/golang:latest
全局注册表支持

要使专用注册表全局可用,请查看server configuration docs.

commands

每个流水线步骤的命令都是串行执行的,就像将它们输入到本地 shell 中一样.

 pipeline:
   backend:
     image: golang
     commands:
+      - go build
+      - go test

这里没有任何魔法.上述命令将转换为简单的 shell 脚本.上面示例中的命令大致转换为以下脚本:

#!/bin/sh
set -e

go build
go test

然后,上述shell脚本作为容器的入口被执行.下面的docker命令是一个（不完整的）例子,说明了该脚本是如何执行的:

docker run --entrypoint=build.sh golang

请注意,只有构建步骤可以定义命令.你不能对插件或服务使用命令.

environment

悟空提供了将环境变量传递给各个流水线步骤的功能.

有关更多详细信息,请查看环境文档.

secrets

悟空提供了将命名参数存储在中央机密存储中YAML配置文件外部的功能.这些机密可以在运行时传递到流水线的各个步骤.

有关更多详细信息,请查看机密文档.

failure

可能允许某些流水线步骤失败,而不会导致整个流水线报告失败（例如,执行 linting 检查的步骤）.若要启用此功能,请添加failure: ignore到流水线步骤.如果悟空在执行该步骤时遇到错误,它会将其报告为失败,但仍执行流水线的后续步骤（如果有）,而不会影响流水线的状态.

 pipeline:
   backend:
     image: golang
     commands:
       - go build
       - go test
+    failure: ignore

when - 条件行执

悟空支持通过使用when块来定义流水线步骤的条件列表.如果when块中的至少一个条件评估为真,则执行该步骤,否则跳过该步骤.条件可以是类似以下的检查:

 pipeline:
   slack:
     image: plugins/slack
     settings:
       channel: dev
+    when:
+      - event: pull_request
+        repo: test/test
+      - event: push
+        branch: main

repo

存储库的条件执行示例:

 pipeline:
   slack:
     image: plugins/slack
     settings:
       channel: dev
+    when:
+      - repo: test/test

branch

:::注意 分支条件不适用于标记. :::

按分支执行条件的示例:

pipeline:
  slack:
    image: plugins/slack
    settings:
      channel: dev
+   when:
+     - branch: master

该步骤现在在master上触发,但也在pull请求的目标分支是master的情况下触发.添加一个事件条件,将其进一步限制为仅在master上推送.

如果分支是master或develop,则执行步骤`:

when:
  - branch: [master, develop]

如果分支以prefix/*开头,则执行步骤:

when:
  - branch: prefix/*

分支匹配使用doublestaropen in new window,注意以*开头的模式应该放在引号之间,而字面的/需要转义.举几个例子:

  • *\\/*以匹配正好有1个/的模式.
  • *\\/** 匹配至少有一个/的模式.
  • *匹配没有/的模式
  • **匹配所有内容

使用自定义包括和排除逻辑执行一个步骤:

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

event

:::信息 默认情况下,步骤按以下事件类型进行过滤

push, pull_request, tag, deployment, manual. :::

可用事件: push, pull_request, tag, deployment, manual

如果构建事件是tag则执行一个步骤:

when:
  - event: tag

如果流水线事件是push到指定分支,则执行一个步骤:

when:
  - event: push
+   branch: main

为多个事件执行一个步骤:

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

tag

此过滤器仅适用于标签事件. 如果标签名称以v开头,请使用glob表达式执行一个步骤:

when:
  - event: tag
    tag: v*

status

有一些在失败时执行流水线步骤的用例,例如为失败的流水线发送通知.即使流水线失败,也使用状态约束来执行步骤:

pipeline:
  slack:
    image: plugins/slack
    settings:
      channel: dev
+   when:
+     - status: [ success, failure ]

platform

:::笔记 此条件应与矩阵流水线结合使用,因为普通管道只能由一个代理执行,而这个代理只有一个拱门. :::

为特定平台执行一个步骤:

when:
  - platform: linux/amd64

使用通配符为特定平台执行一个步骤:

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

environment

执行与目标部署环境匹配的部署事件的步骤:

when:
  - environment: production
  - event: deployment

matrix

为单个矩阵排列执行一个步骤:

when:
  - matrix:
      GO_VERSION: 1.5
      REDIS_VERSION: 2.8

instance

仅在与指定主机名匹配的特定悟空实例上执行步骤:

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

path

:::信息 路径条件仅适用于推送和拉取请求事件 :::

仅在更改某些文件的流水线上执行一个步骤:

when:
  - path: "src/*"

您可以使用glob模式open in new window来匹配更改的文件,并指定如果与该模式匹配的文件已更改include或某些文件未更改exclude则该步骤是否应运行

when:
  - path:
      include: [ '.woodpecker/*.yml', '*.ini' ]
      exclude: [ '*.md', 'docs/**' ]
      ignore_message: "[ALL]"

提示:在提交消息中传递定义的忽略消息,如[ALL]将忽略所有路径条件

evaluate

仅当提供的求值表达式等于true时,才执行一个步骤.每个CI_variable都可以在表达式中使用.

表达式语法可以在底层库的文档open in new window中找到.

在推送到存储库owner/repo的默认分支时运行

when:
  - evaluate: 'CI_BUILD_EVENT == "push" && CI_REPO == "owner/repo" && CI_COMMIT_BRANCH == CI_REPO_DEFAULT_BRANCH'

在用wukong创建的提交上运行:

when:
  - evaluate: 'CI_COMMIT_AUTHOR == "wukong"'

跳过所有含有please ignore me的提交信息的提交内容:

when:
  - evaluate: 'not (CI_COMMIT_MESSAGE contains "please ignore me")'

使用标签deploy在拉取请求上运行:

when:
  - evaluate: 'CI_COMMIT_PULL_REQUEST_LABELS contains "deploy"'

group - 并行执行

悟空支持同机扇入和扇出的并行步进执行.并行步骤使用group属性进行配置.这指示流水线运行器并行执行命名组.

并行配置示例:

 pipeline:
   backend:
+    group: build
     image: golang
     commands:
       - go build
       - go test
   frontend:
+    group: build
     image: node
     commands:
       - npm install
       - npm run test
       - npm run build
   publish:
     image: plugins/docker
     repo: octocat/hello-world

在上述示例中,frontend和backend步骤是并行执行的.在组完成之前,流水线运行器不会执行publish步骤.

volumes

悟空提供了在YAML中定义Docker卷的能力.您可以使用此参数将主机上的文件或文件夹挂载到容器中.

有关更多详细信息,请查看卷文档.

detach

悟空提供了分离步骤的能力,以在后台运行它们,直到流水线完成.

有关更多详细信息,请查看服务文档.

directory

使用directory,您可以在存储库的子目录或Docker容器内设置命令运行的绝对路径.

services

悟空可以提供服务容器.例如,它们可用于在执行流水线期间运行数据库或缓存容器.

有关更多详细信息,请查看服务文档.

workspace

工作区定义了所有流水线步骤共享的共享卷和工作目录.默认工作区根据您的存储库URL匹配以下模式.

/woodpecker/src/github.com/octocat/hello-world

可以使用YAML文件中的工作区块自定义工作区:

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

 pipeline:
   build:
     image: golang:latest
     commands:
       - go get
       - go test

基础属性定义了可用于所有流水线步骤的共享基础卷.这可以确保您的源代码、依赖项和编译的二进制文件在步骤之间持久和共享.

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

 pipeline:
   deps:
     image: golang:latest
     commands:
       - go get
       - go test
   build:
     image: node:latest
     commands:
       - go build

这相当于以下docker命令:

docker volume create my-named-volume

docker run --volume=my-named-volume:/go golang:latest
docker run --volume=my-named-volume:/go node:latest

路径属性定义了构建的工作目录.这是您的代码被克隆的地方,并且将是构建过程中每个步骤的默认工作目录.路径必须是相对的,并与您的基本路径相结合.

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

git clone https://github.com/octocat/hello-world \
  /go/src/github.com/octocat/hello-world

matrix

悟空集成了对矩阵构建的支持.悟空为矩阵中的每个组合执行单独的构建任务,允许您针对多个配置构建和测试单个提交.

有关更多详细信息,请查看矩阵构建文档. For more details check the matrix build docs.

platform

要将您的流水线配置为仅在具有特定平台的代理上执行,您可以使用platform密钥.看看可用平台的官方go文档open in new window.该平台的语法是GOOS/GOARCH,如linux/arm64或linux/amd64.

示例:

假设我们有两个代理,一个arm和一个amd64.以前,这条流水线会在任一代理上执行,因为悟空对流水线的运行位置并不挑剔.通过设置以下选项,它只会在平台为linux/arm64的代理上执行

+platform: linux/arm64

pipeline:
  build:
    image: golang
    commands:
      - go build
      - go test

labels

您可以为流水线设置标签,以选择要执行流水线的代理.当分配给流水线的每个标签与代理标签匹配时,代理将拾取并运行流水线.

要设置其他代理标签,请检查代理配置选项.代理将至少有四个默认标签:platform=agent-os/agent-arch, hostname=my-agent, backend=docker（代理后端类型）和repo=*.代理可以使用*作为标签的通配符.例如repo=*将匹配每个repo.

带有空值的流水线标签将被忽略.默认情况下,每个流水线至少具有repo=your-user/your-repo-name标签.如果您为流水线设置了平台属性,它也将有一个标签,如platform=your-os/your-arch.

您可以添加其他标签作为关键值映射:

+labels:
+  location: europe # only agents with `location=europe` or `location=*` will be used
+  weather: sun
+  hostname: "" # this label will be ignored as it is empty

pipeline:
  build:
    image: golang
    commands:
      - go build
      - go test

variables

悟空在流水线配置中支持YAML 锚点和别名open in new window .这些可以用作变量,不要重复自己.

有关更多详细信息和示例,请查看高级YAML语法文档

clone

如果没有明确定义,悟空会自动配置默认克隆步骤.使用local后端时,plugin-git二进制文件必须位于您的$PATH上,默认克隆步骤才能工作.如果没有,您仍然可以编写手动克隆步骤.

您可以在流水线中手动配置克隆步骤进行自定义:

+clone:
+  git:
+    image: woodpeckerci/plugin-git

 pipeline:
   build:
     image: golang
     commands:
       - go build
       - go test

覆盖深度的配置示例:

 clone:
   git:
     image: woodpeckerci/plugin-git
+    settings:
+      partial: false
+      depth: 50

使用自定义克隆插件的配置示例:

clone:
  git:
+   image: octocat/custom-git-plugin

克隆Mercurial存储库的配置示例:

 clone:
   hg:
+    image: plugins/hg
+    settings:
+      path: bitbucket.org/foo/bar

Git子模块

要使用克隆存储库的凭据来克隆其子模块,请更新.gitmodules以使用https而不是git:

 [submodule "my-module"]
 path = my-module
-url = git@github.com:octocat/my-module.git
+url = https://github.com/octocat/my-module.git

要在.gitmodules中为使用ssh克隆的用户使用ssh git网址,同时在悟空中使用https网址,请添加submodule_override:

 clone:
   git:
     image: woodpeckerci/plugin-git
     settings:
       recursive: true
+      submodule_override:
+        my-module: https://github.com/octocat/my-module.git

pipeline:
  ...

skip_clone

默认情况下,悟空会自动添加克隆步骤.这个克隆步骤可以通过克隆属性进行配置.如果您根本不需要clone步骤,您可以使用以下方法跳过它:

skip_clone: true

when - 全局流水线状况

悟空提供了根据特定条件通过when块跳过整个流水线（而不仅仅是步骤#when---conditional-execution-1）的能力.如果when块中的所有条件评估为真,流水线将被执行,否则它将被跳过,但被视为成功,其他流水线取决于它仍将继续.

repo

按存储库条件执行示例:

+when:
+  repo: test/test
+
 pipeline:
   slack:
     image: plugins/slack
     settings:
       channel: dev

branch

:::笔记 分支条件不适用于标签. :::

分支条件执行示例:

+when:
+  branch: master
+
 pipeline:
   slack:
     image: plugins/slack
     settings:
       channel: dev

该步骤现在在主服务器上触发,但如果拉取请求的目标分支是master.添加一个事件条件,将其进一步限制为仅推送主服务器.

如果分支是master或develop,则执行一个步骤:

when:
  branch: [master, develop]

如果分支以前prefix/*开头,请执行一个步骤:

when:
  branch: prefix/*

使用自定义包含和排除逻辑执行一个步骤:

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

event

如果构建事件是tag则执行一个步骤:

when:
  event: tag

如果流水线事件是push到指定分支,则执行一个步骤:

when:
  event: push
+ branch: main

为所有非拉取请求事件执行一个步骤:

when:
  event: [push, tag, deployment]

为所有构建事件执行一个步骤:

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

tag

这个过滤器只适用于标签事件. 如果标签名称以v开头,则使用glob表达式来执行一个步骤:

when:
  event: tag
  tag: v*

environment

执行与目标部署环境匹配的部署事件的步骤:

when:
  environment: production
  event: deployment

instance

仅在与指定主机名匹配的特定悟空实例上执行步骤:

when:
  instance: stage.woodpecker.company.com

path

:::信息 路径条件仅适用于推送和拉取请求事件 :::

仅在更改某些文件的流水线上执行一个步骤:

when:
  path: "src/*"

您可以使用glob模式open in new window来匹配更改的文件,并指定如果与该模式匹配的文件已更改include或某些文件未更改exclude则该步骤是否应运行.

when:
  path:
    include: [ '.woodpecker/*.yml', '*.ini' ]
    exclude: [ '*.md', 'docs/**' ]
    ignore_message: "[ALL]"

Hint: Passing a defined ignore-message like [ALL] inside the commit message will ignore all path conditions.

depends_on

悟空支持为一个存储库定义多个工作流程.这些工作流的运行是相互独立的.要使它们相互依赖,你可以使用 depends_onopen in new window 关键字.

Privileged mode

悟空提供了在YAML中配置特权模式的能力.您可以使用此参数启动具有升级功能的容器.

特权模式仅适用于受信任的存储库,出于安全原因,仅应在私人环境中使用.请参阅项目设置以启用受信任模式.

 pipeline:
   build:
     image: docker
     environment:
       - DOCKER_HOST=tcp://docker:2375
     commands:
       - docker --tls=false ps

 services:
   docker:
     image: docker:dind
     command: [ "--storage-driver=vfs", "--tls=false" ]
+    privileged: true