when指令允许Pipeline根据给定条件确定是否应执行该阶段。

@[TOC]

when指令概述

when指令允许Pipeline根据给定条件确定是否应执行该阶段。该when指令必须至少包含一个条件。如果when指令包含多个条件,则所有子条件必须返回true才能执行该阶段。这与子条件嵌套在allOf条件中的情况相同(参见下面的示例)。如果使用anyOf条件,请注意一旦找到第一个true条件,条件就会跳过剩余的测试条件。

更复杂的条件结构可使用嵌套条件建:notallOfanyOf。嵌套条件可以嵌套到任意深度。

  • 是否必须: 非必须
  • 参数: 没有
  • 所在位置: 在stage指令内

内置条件

branch

当正在构建的分支与给定的分支模式匹配时执行阶段。如 when { branch 'master' } . 这仅在多分支Pipeline中有效。

buildingTag

构建构建标记时执行阶段。例: when { buildingTag() }

changelog

如果构建的SCM更新日志包含给定的正则表达式模式,则执行该阶段 例如: when { changelog '.*^\\[DEPENDENCY\\] .+$' }

changeset

如果构建的SCM变更集包含与给定字符串或glob匹配的一个或多个文件,则执行该阶段。 例如: when { changeset "**/*.js" }

默认情况下,路径匹配不区分大小写,可以使用caseSensitive参数关闭, 例如: when { changeset glob: "ReadMe.*", caseSensitive: true }

changeRequest

如果当前构建用于“更改请求”(GitHub和Bitbucket上的Pull Request,GitLab上的Merge请求或Gerrit中的change等),则执行该阶段。 如果没有传递任何参数,则每个更改请求都会运行该阶段, 例如: when { changeRequest() }.

通过向变更请求添加带参数的过滤器属性,可以使阶段仅在匹配的变更请求上运行。 可能的属性是id,target,branch,fork,url,title,author,authorDisplayName和authorEmail。 其中每个对应一个CHANGE_*环境变量, 例如: when { changeRequest target: 'master' }.

可以在属性之后添加可选参数比较器,以指定如何评估匹配的任何模式:EQUALS用于简单字符串比较(默认值),GLOB用于ANT样式路径glob(与例如变更集相同)或REGEXP用于常规 表达匹配。例如: when { changeRequest authorEmail: "[\\w_-.]+@example.com", comparator: 'REGEXP' }

environment

当指定的环境变量设置为给定值时执行阶段, 例如: when { environment name: 'DEPLOY_TO', value: 'production' }

equals

当期望值等于实际值时执行阶段, 例如: when { equals expected: 2, actual: currentBuild.number }

expression

当指定的Groovy表达式求值为true时执行阶段,例如: when { expression { return params.DEBUG_BUILD } } .

请注意,从表达式返回字符串时,必须将它们转换为布尔值或返回null表示为false。 简单地返回0false仍将评估为true

tag

如果TAG_NAME变量与给定模式匹配,则执行该阶段。例如: when { tag "release-*" }.

如果提供了空模式,则如果TAG_NAME变量存在,则将执行该阶段(与buildingTag()相同)。

可以在属性之后添加可选参数比较器,以指定如何评估匹配的任何模式:EQUALS用于简单字符串比较(默认值),GLOB用于ANT样式路径glob(与例如变更集相同)或REGEXP用于常规 表达匹配。 例如: when { tag pattern: "release-\\d+", comparator: "REGEXP"}

not

嵌套条件为false时执行阶段。 必须包含一个条件。 例如: when { not { branch 'master' } }

allOf

当所有嵌套条件都为真时执行阶段。 必须至少包含一个条件。例如: when { allOf { branch 'master'; environment name: 'DEPLOY_TO', value: 'production' } }

anyOf

至少有一个嵌套条件为真时执行阶段。 必须至少包含一个条件。例如: when { anyOf { branch 'master'; branch 'staging' } }

在进入stage's agent之前评估when
默认情况下,进入该阶段的agent后,对该阶段的when条件进行评估。 但是,可以通过在when块中指定beforeAgent选项来更改此设置。 如果beforeAgent设置为true,则首先评估when条件,并且仅当when条件的计算结果为true时才进入agent

示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
Jenkinsfile (Declarative Pipeline)
pipeline {
agent any
stages {
stage('Example Build') {
steps {
echo 'Hello World'
}
}
stage('Example Deploy') {
when {
branch 'production'
}
steps {
echo 'Deploying'
}
}
}
}
Jenkinsfile (Declarative Pipeline)
pipeline {
agent any
stages {
stage('Example Build') {
steps {
echo 'Hello World'
}
}
stage('Example Deploy') {
when {
branch 'production'
environment name: 'DEPLOY_TO', value: 'production'
}
steps {
echo 'Deploying'
}
}
}
}
Jenkinsfile (Declarative Pipeline)
pipeline {
agent any
stages {
stage('Example Build') {
steps {
echo 'Hello World'
}
}
stage('Example Deploy') {
when {
allOf {
branch 'production'
environment name: 'DEPLOY_TO', value: 'production'
}
}
steps {
echo 'Deploying'
}
}
}
}
Jenkinsfile (Declarative Pipeline)
pipeline {
agent any
stages {
stage('Example Build') {
steps {
echo 'Hello World'
}
}
stage('Example Deploy') {
when {
branch 'production'
anyOf {
environment name: 'DEPLOY_TO', value: 'production'
environment name: 'DEPLOY_TO', value: 'staging'
}
}
steps {
echo 'Deploying'
}
}
}
}
Jenkinsfile (Declarative Pipeline)
pipeline {
agent any
stages {
stage('Example Build') {
steps {
echo 'Hello World'
}
}
stage('Example Deploy') {
when {
expression { BRANCH_NAME ==~ /(production|staging)/ }
anyOf {
environment name: 'DEPLOY_TO', value: 'production'
environment name: 'DEPLOY_TO', value: 'staging'
}
}
steps {
echo 'Deploying'
}
}
}
}
Jenkinsfile (Declarative Pipeline)
pipeline {
agent none
stages {
stage('Example Build') {
steps {
echo 'Hello World'
}
}
stage('Example Deploy') {
agent {
label "some-label"
}
when {
beforeAgent true
branch 'production'
}
steps {
echo 'Deploying'
}
}
}
}

Pipeline中使用tag

使用标签来驱动Jenkins管道中的行为。考虑以下设计Jenkinsfile,其中包含构建,测试和部署的三个基本阶段:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
pipeline {
agent any
stages {
stage('Build') {
steps {
sh 'make package'
}
}
stage('Test') {
steps {
sh 'make check'
}
}
stage('Deploy') {
when { tag "release-*" }
steps {
echo 'Deploying only because this commit is tagged...'
sh 'make deploy'
}
}
}
}

特别值得注意的是 when Deploy阶段的tag条件是应用标准。这意味着只有在Git中与release-* Ant样式通配符匹配的标记触发Pipeline时,才会执行该阶段。

参考

  1. https://jenkins.io/doc/book/pipeline/syntax/#when
  2. https://jenkins.io/blog/2018/05/16/pipelines-with-git-tags/