Jenkins_流水线语法_002

参数

parameters 指令提供了一个用户在触发流水线时应该提供的参数列表。这些用户指定参数的值可通过 params 对象提供给流水线步骤, 了解更多请参考示例。

Required	No
Parameters	None
Allowed	Only once, inside the pipeline block.

可用参数

string 字符串类型的参数, 例如: parameters { string(name: 'DEPLOY_ENV', defaultValue: 'staging', description: '') }
booleanParam 布尔参数, 例如: parameters { booleanParam(name: 'DEBUG_BUILD', defaultValue: true, description: '') }

示例

Jenkinsfile (Declarative Pipeline)

pipeline {
    agent any
    parameters {
        string(name: 'PERSON', defaultValue: 'Mr Jenkins', description: 'Who should I say hello to?')
    }
    stages {
        stage('Example') {
            steps {
                echo "Hello ${params.PERSON}"
            }
        }
    }
}

	一份完整的可用参数列表正在等待 INFRA-1503的完成。

触发器

triggers 指令定义了流水线被重新触发的自动化方法。对于集成了源（比如 GitHub 或 BitBucket）的流水线, 可能不需要 triggers ，因为基于 web 的集成很肯能已经存在。当前可用的触发器是 cron, pollSCM 和 upstream。

Required	No
Parameters	None
Allowed	Only once, inside the pipeline block.

cron 接收 cron 样式的字符串来定义要重新触发流水线的常规间隔 ,比如: triggers { cron('H */4 * * 1-5') }
pollSCM 接收 cron 样式的字符串来定义一个固定的间隔，在这个间隔中，Jenkins 会检查新的源代码更新。如果存在更改, 流水线就会被重新触发。例如: triggers { pollSCM('H */4 * * 1-5') }
upstream 接受逗号分隔的工作字符串和阈值。当字符串中的任何作业以最小阈值结束时，流水线被重新触发。例如: triggers { upstream(upstreamProjects: 'job1,job2', threshold: hudson.model.Result.SUCCESS) }

	pollSCM 只在Jenkins 2.22 及以上版本中可用。

示例

Jenkinsfile (Declarative Pipeline)

pipeline {
    agent any
    triggers {
        cron('H */4 * * 1-5')
    }
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

stage

stage 指令在 stages 部分进行，应该包含一个实际上, 流水巷所做的所有实际工作都将封装进一个或多个 stage 指令中。

Required	At least one
Parameters	One mandatory parameter, a string for the name of the stage.
Allowed	Inside the stages section.

示例

Jenkinsfile (Declarative Pipeline)

pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

工具

定义自动安装和放置 PATH 的工具的一部分。如果 agent none 指定，则忽略该操作。

Required	No
Parameters	None
Allowed	Inside the pipeline block or a stage block.

支持工具

maven
jdk
gradle

示例

Jenkinsfile (Declarative Pipeline)

pipeline {
    agent any
    tools {
        maven 'apache-maven-3.0.1' 
    }
    stages {
        stage('Example') {
            steps {
                sh 'mvn --version'
            }
        }
    }
}

	The tool name must be pre-configured in Jenkins under Manage Jenkins → Global Tool Configuration.
	工具名称必须在Jenkins中的Manage Jenkins→全局工具配置下预先配置。

input

stage 的 input 指令允许你使用 input step提示输入。在应用了 options 后，进入 stage 的 agent 或评估 when 条件前， stage 将暂停。如果 input 被批准, stage 将会继续。作为 input 提交的一部分的任何参数都将在环境中用于其他 stage。

配置项

message 必需的。这将在用户提交 input 时呈现给用户。
id input 的可选标识符，默认为 stage 名称。
ok input表单上的”ok” 按钮的可选文本。
submitter 可选的以逗号分隔的用户列表或允许提交 input 的外部组名。默认允许任何用户。
submitterParameter 环境变量的可选名称。如果存在，用 submitter 名称设置。
parameters 提示提交者提供的一个可选的参数列表。更多信息参见 [parameters]。

示例

Jenkinsfile (Declarative Pipeline)

pipeline {
    agent any
    stages {
        stage('Example') {
            input {
                message "Should we continue?"
                ok "Yes, we should."
                submitter "alice,bob"
                parameters {
                    string(name: 'PERSON', defaultValue: 'Mr Jenkins', description: 'Who should I say hello to?')
                }
            }
            steps {
                echo "Hello, ${PERSON}, nice to meet you."
            }
        }
    }
}

when

when 指令允许流水线根据给定的条件决定是否应该执行阶段。 when 指令必须包含至少一个条件。如果 when 指令包含多个条件, 所有的子条件必须返回True，阶段才能执行。这与子条件在 allOf 条件下嵌套的情况相同 (参见下面的示例)。

使用诸如 not, allOf, 或 anyOf 的嵌套条件可以构建更复杂的条件结构 can be built 嵌套条件刻意潜逃到任意深度。

Required	No
Parameters	None
Allowed	Inside a stage directive

内置条件

branch 当正在构建的分支与模式给定的分支匹配时，执行这个阶段, 例如: when { branch 'master' }。注意，这只适用于多分支流水线。
environment 当指定的环境变量是给定的值时，执行这个步骤, 例如: when { environment name: 'DEPLOY_TO', value: 'production' }
expression 当指定的Groovy表达式评估为true时，执行这个阶段, 例如: when { expression { return params.DEBUG_BUILD } }
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`

默认情况下, 如果定义了某个阶段的代理，在进入该stage 的 agent 后该 stage 的 when 条件将会被评估。但是, 可以通过在 when 块中指定 beforeAgent 选项来更改此选项。如果 beforeAgent 被设置为 true, 那么就会首先对 when 条件进行评估 , 并且只有在 when 条件验证为真时才会进入 agent 。

示例

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'
            }
        }
    }
}

并行

声明式流水线的阶段可以在他们内部声明多隔嵌套阶段, 它们将并行执行。注意，一个阶段必须只有一个 steps 或 parallel 的阶段。嵌套阶段本身不能包含进一步的 parallel 阶段, 但是其他的阶段的行为与任何其他 stage 相同。任何包含 parallel 的阶段不能包含 agent 或 tools 阶段, 因为他们没有相关 steps。

另外, 通过添加 failFast true 到包含 parallel的 stage 中，当其中一个进程失败时，你可以强制所有的 parallel 阶段都被终止。

示例

Jenkinsfile (Declarative Pipeline)

pipeline {
    agent any
    stages {
        stage('Non-Parallel Stage') {
            steps {
                echo 'This stage will be executed first.'
            }
        }
        stage('Parallel Stage') {
            when {
                branch 'master'
            }
            failFast true
            parallel {
                stage('Branch A') {
                    agent {
                        label "for-branch-a"
                    }
                    steps {
                        echo "On Branch A"
                    }
                }
                stage('Branch B') {
                    agent {
                        label "for-branch-b"
                    }
                    steps {
                        echo "On Branch B"
                    }
                }
            }
        }
    }
}

步骤

声明式流水线可能使用在流水线步骤引用中记录的所有可用的步骤, 它包含一个完整的步骤列表, 其中添加了下面列出的步骤，这些步骤只在声明式流水线中 only supported 。

脚本

script 步骤需要 [scripted-pipeline]块并在声明式流水线中执行。对于大多数用例来说,应该声明式流水线中的“脚本”步骤是不必要的，但是它可以提供一个有用的”逃生出口”。非平凡的规模和/或复杂性的 script 块应该被转移到共享库。

示例

Jenkinsfile (Declarative Pipeline)

pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'

                script {
                    def browsers = ['chrome', 'firefox']
                    for (int i = 0; i < browsers.size(); ++i) {
                        echo "Testing the ${browsers[i]} browser"
                    }
                }
            }
        }
    }
}

脚本化流水线

脚本化流水线, 与[declarative-pipeline]一样的是, 是建立在底层流水线的子系统上的。与声明式不同的是, 脚本化流水线实际上是由 Groovy构建的通用 DSL [2]。 Groovy 语言提供的大部分功能都可以用于脚本化流水线的用户。这意味着它是一个非常有表现力和灵活的工具，可以通过它编写持续交付流水线。

流控制

脚本化流水线从 Jenkinsfile 的顶部开始向下串行执行, 就像 Groovy 或其他语言中的大多数传统脚本一样。因此，提供流控制取决于 Groovy 表达式, 比如 if/else 条件, 例如:

Jenkinsfile (Scripted Pipeline)

node {
    stage('Example') {
        if (env.BRANCH_NAME == 'master') {
            echo 'I only execute on the master branch'
        } else {
            echo 'I execute elsewhere'
        }
    }
}

另一种方法是使用Groovy的异常处理支持来管理脚本化流水线流控制。当步骤失败，无论什么原因，它们都会抛出一个异常。处理错误的行为必须使用Groovy中的 try/catch/finally 块 , 例如:

Jenkinsfile (Scripted Pipeline)

node {
    stage('Example') {
        try {
            sh 'exit 1'
        }
        catch (exc) {
            echo 'Something failed, I should sound the klaxons!'
            throw
        }
    }
}

步骤

正如本章开始所讨论的, 流水线最基础的部分是”步骤”。从根本上说, 步骤告诉 Jenkins要做 what ，并作为声明式和脚本化流水线已发的基本构建块。

脚本化流水线 not 不引入任何特定于其语法的步骤; 流水线步骤引用包括流水线和插件提供的步骤的完整列表。

区别普通 Groovy

为了提供 durability, 这意味着运行流水线可以在Jenkins master 重启后继续运行，脚本化的流水线序列化数据到主服务器。由于这个设计需求, 一些Groovy 习惯用语，比如 collection.each { item -> /* perform operation */ } 都不完全支持。详情参见 JENKINS-27421 和 JENKINS-26481。

语法比较

当Jenkins 流水线第一次构建时, Groovy 被选为基础。 Jenkins长期使用嵌入式 Groovy引擎来为管理员和用户提供高级脚本功能。另外, Jenkins流水线的实现者发现 Groovy是构建现在成为 “脚本化流水线” DSL的坚实基础 [2]。

由于它是一个功能齐全的编程环境, 脚本化流水线为Jenkins用户提供了大量的灵活性性和可扩展性。 Groovy学习曲线通常不适合给定团队的所有成员, 因此创造了声明式流水线来为编写Jenkins流水线提供一种更简单、更有主见的语法。

两者本质上是相同的流水线子系统。 underneath. 他们都是 “流水线即代码” 的持久实现。它们都能够使用构建到流水线中或插件提供的步骤。它们都能够使用共享库

但是它们的区别在于语法和灵活性。声明式限制了用户使用更严格和预定义的结构，使其成为更简单的持续交付流水线的理想选择。脚本化提供了很少的限制, 以至于对脚本和语法的唯一限制往往是由Groovy子集本身定义的，而不是任何特定于流水线的系统, 这使他成为权利用户和那些有更复杂需求的人的理想选择。顾名思义, 声明式流水线鼓励声明式编程模型。 [3] 而脚本化流水线遵循一个更命令式的编程模型 [4]

Jenkins_流水线语法_002

参数

可用参数

示例

触发器

示例

stage

示例

工具

支持工具

示例

input

配置项

示例

when

内置条件

在进入 stage 的 agent 前评估 when

示例

并行

示例

步骤

脚本

示例

脚本化流水线

流控制

步骤

区别普通 Groovy

语法比较

在进入 `stage` 的 `agent` 前评估 `when`