参数
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)
代码语言：javascript复制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)
代码语言：javascript复制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)
代码语言：javascript复制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)
代码语言：javascript复制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)
代码语言：javascript复制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)
代码语言：javascript复制pipeline {
agent any
stages {
stage('Example Build') {
steps {
echo 'Hello World'
}
}
stage('Example Deploy') {
when {
branch 'production'
}
steps {
echo 'Deploying'
}
}
}
}Jenkinsfile (Declarative Pipeline)
代码语言：javascript复制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)
代码语言：javascript复制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)
代码语言：javascript复制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)
代码语言：javascript复制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)
代码语言：javascript复制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)
代码语言：javascript复制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)
代码语言：javascript复制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)
代码语言：javascript复制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)
代码语言：javascript复制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]
