Jenkins Pipeline中when的用法

用于学习记录。参考Jenkins官方文档进行翻译补充示例。以英文文档为基准，以中文文档作为辅助。
翻译自：
Jenkins when 英文文档
参考：
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-正则表达式