目录
用于学习记录。参考Jenkins官方文档进行翻译补充示例。以英文文档为基准，以中文文档作为辅助。
翻译自：
Jenkins when 英文文档
概述
When 指令允许 Pipeline 根据给定条件确定是否应执行该阶段。When指令必须至少包含一个条件。如果when指令包含多个条件，则所有子条件都必须返回true才能执行该阶段。这与子条件嵌套在 allOf 条件中相同（请参阅下面的示例）。如果使用 anyOf 条件，请注意，一旦找到第一个"true"条件，该条件就会跳过剩余的测试。
可以使用嵌套条件构建更复杂的条件结构：not、allOf 或anyOf。嵌套条件可以嵌套到任意深度。
内置条件
branch
当正在构建的分支与模式给定的分支匹配时，执行这个阶段, 例如: when { branch 'master' }。注意，这只适用于多分支流水线。
可选参数comparator 可以添加在属性之后，以指定如何评估任何模式的匹配：
EQUALS用于简单的字符串比较GLOB（默认）用于ANT 样式路径glob(和下面changeset的例子一样)REGEXP用于正则表达式匹配
例如：when { branch pattern: "release-\\d+", comparator: "REGEXP"}
buildingTag
当构建为正在buildingTag时执行该阶段。例如 For example: when { buildingTag() }
changeset
如果构建的 SCM 变更集包含一个或多个与给定模式匹配的文件，则执行该阶段。
例子：
when { changeset "**/*.js" }
changeRequest
如果当前构建是针对"更改请求"（也称为 GitHub 和 Bitbucket 上的拉取请求、GitLab 上的合并请求、Gerrit 中的更改等），则执行该阶段。
当没有传递参数时，该阶段会在每个更改请求上运行，例如：when { changeRequest() }
通过向变更请求添加带有参数的过滤器属性，可以使该阶段仅在匹配的变更请求时运行。可以使用的属性有 id、target、branch、fork、url、title、author、authorDisplayName 和authorEmail。其中每一个都对应于一个CHANGE_*环境变量，
例如:
when { changeRequest target: 'master' }.
可选参数comparator 可以添加在属性之后，以指定如何评估任何模式的匹配：
EQUALS用于简单的字符串比较GLOB（默认）用于ANT 样式路径glob(和下面changeset的例子一样)REGEXP用于正则表达式匹配
例如：
when { changeRequest authorEmail: "[\\w_-.]+@example.com", comparator: 'REGEXP' }
equals
当期望值等于实际值时执行该阶段，例如：
when { equals expected: 2, actual: currentBuild.number }
expression
当指定的Groovy表达式评估为true时，执行这个阶段, 例如:
when { expression { return params.DEBUG_BUILD } }
注意：
从表达式返回字符串时，必须将它们转换为布尔值或返回null以计算为 false。简单地返回"0"或"false"仍将计算为"true"。
triggeredBy
触发者 当给定的参数触发当前构建时执行该阶段。例如：
when { triggeredBy 'SCMTrigger' }when { triggeredBy 'TimerTrigger' }when { triggeredBy 'BuildUpstreamCause' }when { triggeredBy cause: "UserIdCause", detail: "vlinde" }
tag
如果 TAG_NAME变量与给定模式匹配，则执行该阶段。例如：when { tag "release-*" }
如果提供了空模式，则如果 TAG_NAME 变量存在，则该阶段将执行（与buildingTag() 相同）。
可选参数comparator 可以添加在属性之后，以指定如何评估任何模式的匹配：
EQUALS用于简单的字符串比较GLOB（默认）用于ANT 样式路径glob(和下面changeset的例子一样)REGEXP用于正则表达式匹配
比如：
when { tag pattern: "release-\\d+", comparator: "REGEXP"}
environment
当指定的环境变量是给定的值时，执行这个步骤,
例如: when { environment name: 'DEPLOY_TO', value: 'production' }
not
当嵌套条件是错误时，执行这个阶段,必须包含一个条件，
例如: when { not { branch 'master' } }
allOf
当所有的嵌套条件都正确时，执行这个阶段,必须包含至少一个条件，
例如: when { allOf { branch 'master'; environment name: 'DEPLOY_TO', value: 'production' } }
anyOf
当至少有一个嵌套条件为真时，执行这个阶段,必须包含至少一个条件，
例如: when { anyOf { branch 'master'; branch 'staging' } }
在进入 stage 的 agent 前评估 when
beforeAgent
默认情况下, 如果定义了某个阶段的agent，在进入该stage 的 agent 后该 stage 的 when 条件将会被评估。但是, 可以通过在 when 块中指定 beforeAgent 选项来更改此选项。 如果 beforeAgent 被设置为 true, 那么就会首先对 when 条件进行评估 , 并且只有在 when 条件验证为真时才会进入 agent
beforeInput
在输入指令之前评估when 默认情况下，如果定义了阶段的条件，则在输入之前不会评估阶段的条件。但是，可以通过在when块中指定beforeInput选项来更改这一点。如果beforeInput设置为true，则将首先评估when条件，并且仅当when条件评估为true时才会输入输入。beforeInput true 优先于 beforeAgent true。 在选项指令之前评估when 默认情况下，将在输入该阶段的选项（如果已定义）后评估该阶段的条件。
beforeOptions
但是，可以通过在 when 块中指定 beforeOptions 选项来更改此设置。如果beforeOptions设置为true，则将首先评估when条件，并且仅当when条件评估为true时才会输入选项。
示例
单一条件、声明性流水线
pipeline {
agent any
stages {
stage('Example Build') {
steps {
echo 'Hello World'
}
}
stage('Example Deploy') {
when {
branch 'production'
}
steps {
echo 'Deploying'
}
}
}
}
多条件、声明式管道
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'
}
}
}
}
嵌套条件（与前面的示例行为相同）
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'
}
}
}
}
多重条件和嵌套条件
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'
}
}
}
}
表达式条件和嵌套条件
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'
}
}
}
}
beforeAgent
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'
}
}
}
}
beforeInput
pipeline {
agent none
stages {
stage('Example Build') {
steps {
echo 'Hello World'
}
}
stage('Example Deploy') {
when {
beforeInput true
branch 'production'
}
input {
message "Deploy to production?"
id "simple-input"
}
steps {
echo 'Deploying'
}
}
}
}
beforeOptions
pipeline {
agent none
stages {
stage('Example Build') {
steps {
echo 'Hello World'
}
}
stage('Example Deploy') {
when {
beforeOptions true
branch 'testing'
}
options {
lock label: 'testing-deploy-envs', quantity: 1, variable: 'deployEnv'
}
steps {
echo "Deploying to ${deployEnv}"
}
}
}
}
triggeredBy
pipeline {
agent none
stages {
stage('Example Build') {
steps {
echo 'Hello World'
}
}
stage('Example Deploy') {
when {
triggeredBy "TimerTrigger"
}
steps {
echo 'Deploying'
}
}
}
}
Groovy正则表达式
上述内容使用正则表达式部分还可以这样写：
when {
expression{
def reg = ~'^v2.*'
def isMatched = (env.TAG_NAME ==~ reg)
return isMatched
}
beforeAgent true
}
在Jenkins的when语法中，没有直接支持使用正则表达式作为条件的内置功能。但是可以使用Groovy语言的正则表达式功能来实现类似的效果。
下面是一个示例，演示如何在Jenkins的when语法中使用Groovy正则表达式：
when {
expression {
return params.BRANCH_NAME ==~ /master.*/
}
}
在上述示例中，params.BRANCH_NAME是一个构建参数，==~是Groovy中用于匹配正则表达式的操作符。正则表达式/master.*/用于匹配以"master"开头的任意字符串。
可以根据需要修改正则表达式以满足匹配要求。
注意：正则表达式的语法可能会因具体的需求而有所不同。在使用正则表达式时，请确保使用适当的语法和模式。
需要注意的是，虽然正则表达式可以在when语法中使用，但它并不是when语法的核心功能。when语法的主要目的是根据条件来控制构建过程的执行，而正则表达式只是其中的一种条件判断方式。
扩展
关于Groovy正则表达式的部分，可以进一步查看：
Groovy-正则表达式