Jenkinsfile (Declarative Pipeline)
pipeline {
agent any
environment {
CC = 'clang'
stages {
stage('Example') {
environment {
AN_ACCESS_KEY = credentials('my-prefined-secret-text')
steps {
sh 'printenv'
3.5、options
该options指令允许在Pipeline本身内配置Pipeline专用选项。Pipeline提供了许多这些选项，例如buildDiscarder，但它们也可能由插件提供，例如timestamps。
buildDiscarder
持久化工件和控制台输出，用于最近Pipeline运行的具体数量。例如：options { buildDiscarder(logRotator(numToKeepStr: '1')) }
disableConcurrentBuilds
不允许并行执行Pipeline。可用于防止同时访问共享资源等。例如：options { disableConcurrentBuilds() }
overrideIndexTriggers
允许覆盖分支索引触发器的默认处理。 如果分支索引触发器在多分支或组织标签中禁用, options { overrideIndexTriggers(true) }将只允许它们用于促工作。否则, options { overrideIndexTriggers(false) }只会禁用改作业的分支索引触发器。
skipDefaultCheckout
在agent指令中默认跳过来自源代码控制的代码。例如：options { skipDefaultCheckout() }
skipStagesAfterUnstable
一旦构建状态进入了“不稳定”状态，就跳过阶段。例如：options { skipStagesAfterUnstable() }
checkoutToSubdirectory
在工作空间的子目录中自动地执行源代码控制检出。例如: options { checkoutToSubdirectory('foo') }
timeout
设置Pipeline运行的超时时间，之后Jenkins应该中止Pipeline。例如：options { timeout(time: 1, unit: 'HOURS') }
retry
失败后，重试整个Pipeline指定的次数。例如：options { retry(3) }
timestamps
预处理由Pipeline生成的所有控制台输出运行时间与发射线的时间。例如：options { timestamps() }
Jenkinsfile (Declarative Pipeline)
pipeline {
agent any
options {
timeout(time: 1, unit: 'HOURS')
stages {
stage('Example') {
steps {
echo 'Hello World'
指定一个小时的全局执行超时，之后Jenkins将中止Pipeline运行。
3.6、parameters
该parameters指令提供用户在触发Pipeline时应提供的参数列表。这些用户指定的参数的值通过该params对象可用于Pipeline步骤。
string
字符串类型的参数，例如：parameters { string(name: 'DEPLOY_ENV', defaultValue: 'staging', description: '') }
文本参数，可以包含多行，例如：parameters { text(name: 'DEPLOY_TEXT', defaultValue: 'One\nTwo\nThree\n', description: '') }
booleanParam
布尔参数，例如：parameters { booleanParam(name: 'DEBUG_BUILD', defaultValue: true, description: '') }
choice
选择参数，例如：parameters { choice(name: 'CHOICES', choices: ['one', 'two', 'three'], description: '') }
password
密码参数，例如：parameters { password(name: 'PASSWORD', defaultValue: 'SECRET', description: 'A secret password') }
pipeline {
agent any
parameters {
string(name: 'PERSON', defaultValue: 'Mr Jenkins', description: 'Who should I say hello to?')
text(name: 'BIOGRAPHY', defaultValue: '', description: 'Enter some information about the person')
booleanParam(name: 'TOGGLE', defaultValue: true, description: 'Toggle this value')
choice(name: 'CHOICE', choices: ['One', 'Two', 'Three'], description: 'Pick something')
password(name: 'PASSWORD', defaultValue: 'SECRET', description: 'Enter a password')
stages {
stage('Example') {
steps {
echo "Hello ${params.PERSON}"
echo "Biography: ${params.BIOGRAPHY}"
echo "Toggle: ${params.TOGGLE}"
echo "Choice: ${params.CHOICE}"
echo "Password: ${params.PASSWORD}"
3.7、triggers
该triggers指令定义了应重新触发的自动化方式。对于与GitHub或BitBucket之类的源集成的管道，triggers由于基于Webhooks的集成可能已经存在，因此可能没有必要。目前可用的触发器 cron，pollSCM和upstream。
接受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) }
// Declarative //
pipeline {
agent any
triggers {
cron('H */4 * * 1-5')
stages {
stage('Example') {
steps {
echo 'Hello World'
更多jenkins cron语法，可参考官方说明
3.8、stage
该stage指令位于该stages节中，并且应包含 steps节，可选agent节或其他特定于阶段的指令。实际上，管道完成的所有实际工作都将包含在一个或多个stage指令中。
// Declarative //
pipeline {
agent any
stages {
stage('Example') {
steps {
echo 'Hello World'
定义自动安装并放在上的工具的部分PATH。如果agent none指定，则将其忽略。
pipeline {
agent any
tools {
maven 'apache-maven-3.0.1'
stages {
stage('Example') {
steps {
sh 'mvn --version'
input指令stage允许使用inputstep提示输入。在stage将暂停任何后options已被应用，并在进入前agent块为stage或评估when的条件stage。如果input批准，stage则将继续。作为input提交的一部分提供的任何参数将在其余的环境中可用stage。
message
必需的，这将在用户提交时显示给用户input
可选标识符input，默认为stage名称
input表单上“确定”按钮的可选文本
submitter
可选的逗号分隔列表，这些列表允许用户提交此用户或外部组名input。默认为允许任何用户。
submitterParameter
环境变量的可选名称，用该submitter名称设置（如果存在）
parameters
提示提交者提供的可选参数列表。请参阅parameters以获取更多信息
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."
3.11、when
该when指令允许Pipeline根据给定的条件确定是否执行该阶段。该when指令必须至少包含一个条件。如果when指令包含多个条件，则所有子条件必须为舞台执行返回true。这与子条件嵌套在一个allOf条件中相同。
更复杂的条件结构可使用嵌套条件建：not，allOf或anyOf。嵌套条件可以嵌套到任意深度。
branch
当正在构建的分支与给出的分支模式匹配时执行阶段，例如：when { branch 'master' }。仅适用于多分支Pipeline。
Jenkinsfile (Declarative Pipeline)
pipeline {
agent any
stages {
stage('Example Build') {
steps {
echo 'Hello World'
stage('Example Deploy') {
when {
branch 'production'
steps {
echo 'Deploying'
environment
当指定的环境变量设置为给定值时执行阶段，例如： when { environment name: 'DEPLOY_TO', value: 'production' }
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'
expression
当指定的Groovy表达式求值为true时执行阶段，例如：when { expression { return params.DEBUG_BUILD } }
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'
当嵌套条件为false时执行阶段。必须包含一个条件。例如：when { not { branch 'master' } }
allOf
当所有嵌套条件都为真时，执行。必须至少包含一个条件。例如：when { allOf { branch 'master'; environment name: 'DEPLOY_TO', value: 'production' } }
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'
anyOf
当至少一个嵌套条件为真时执行。必须至少包含一个条件。例如：when { anyOf { branch 'master'; branch 'staging' } }
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'
3.12、parallel
声明性管道中的阶段可能有一个parallel部分，其中包含要并行运行的嵌套阶段的列表。需要注意的是一个阶段都必须有且只有一个steps，stages，parallel，或matrix。这是不可能的嵌套parallel或matrix块内stage，如果该指令stage指令嵌套在一个parallel或matrix阻塞本身。然而，stage一个内指令parallel或matrix块可以使用的所有其它的功能stage，包括agent，tools，when等。
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"
stage('Branch C') {
agent {
label "for-branch-c"
stages {
stage('Nested 1') {
steps {
echo "In stage Nested 1 within Branch C"
stage('Nested 2') {
steps {
echo "In stage Nested 2 within Branch C"
此外，你可以parallel阶段时，它们中的任何一个发生故障，所有被中止，加入failFast true到stage含有parallel。添加的另一个选项failfast是在管道定义中添加一个选项：parallelsAlwaysFailFast()
pipeline {
agent any
options {
parallelsAlwaysFailFast()
stages {
stage('Non-Parallel Stage') {
steps {
echo 'This stage will be executed first.'
stage('Parallel Stage') {
when {
branch 'master'
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"
stage('Branch C') {
agent {
label "for-branch-c"
stages {
stage('Nested 1') {
steps {
echo "In stage Nested 1 within Branch C"
stage('Nested 2') {
steps {
echo "In stage Nested 2 within Branch C"
4.1、在声明式pipeline中使用脚本
声明式pipeline是不能直接在steps块中写Groovy代码。
Jenkins pipeline专门提供了一个script步骤，你能在script步骤中像写代码一样写pipeline逻辑。
pipeline {
agent any
stages {
stage('Build') {
steps {
script {
result = sh (script: "git log -1|grep 'Release'", returnStatus: true)
echo "result: ${result}"
在script块中的其实就是Groovy代码。大多数时候，我们是不需要使用script步骤的。如果在script步骤中写了大量的逻辑，则说明你应该把这些逻辑拆分到不同的阶段，或者放到共享库中。共享库是一种扩展Jenkins pipeline的技术。
4.2、pipeline内置基础步骤
4.2.1、文件目录相关步骤
deleteDir
删除当前目录，它是一个无参步骤，删除的是当前工作目录。通常它与dir步骤一起使用，用于删除指定目录下的内容。
切换到目录。默认pipeline工作在工作空间目录下，dir步骤可以让我们切换到其它目录。例如：dir("/var/logs") { deleteDir() }
fileExists
判断文件是否存在。fileExists('/tmp/a.jar')判断/tmp/a.jar文件是否存在。如果参数是相对路径，则判断在相对当前工作目录下，该文件是否存在。结果返回布尔类型。
isUnix
判断是否为类Unix系统。如果当前pipeline运行在一个类Unix系统上，则返回true。
确认当前目录。pwd与Linux的pwd命令一样，返回当前所在目录。它有一个布尔类型的可选参数：tmp，如果参数值为true，则返回与当前工作空间关联的临时目录。
writeFile
将内容写入指定文件中。
writeFile支持的参数有：
file：文件路径，可以是绝对路径，也可以是相对路径。
text：要写入的文件内容。
encoding（可选）：目标文件的编码。如果留空，则使用操作系统默认的编码。如果写的是Base64的数据，则可以使用Base64编码。
readFile：读取指定文件的内容，以文本返回。
readFile支持的参数有：
file：路径，可以是绝对路径，也可以是相对路径。
encoding（可选）：读取文件时使用的编码。
script {
// "amVua2lucyBib29r" 是"jenkins book"进行Base64编码后的值
writeFile(file: "base64File", text: "amVua2lucyBib29r", encoding: "Base64")
def content = readFile(file: "base64File", encoding: "UTF-8")
echo "${content}"
// 打印结果: jenkins book
4.2.2、制品相关步骤
stash
保存临时文件。
stash步骤可以将一些文件保存起来，以便被同一次构建的其他步骤或阶段使用。如果整个pipeline的所有阶段在同一台机器上执行，则stash步骤是多余的。所以，通常需要stash的文件都是要跨Jenkins node使用的。
stash步骤会将文件存储在tar文件中，对于大文件的stash操作将会消耗Jenkins master的计算资源。Jenkins官方文档推荐，当文件大小为5∼100MB时，应该考虑使用其他替代方案。
stash步骤的参数列表如下：
name：字符串类型，保存文件的集合的唯一标识。
allowEmpty：布尔类型，允许stash内容为空。
excludes：字符串类型，将哪些文件排除。如果排除多个文件，则使用逗号分隔。留空代表不排除任何文件。
includes：字符串类型，stash哪些文件，留空代表当前文件夹下的所有文件。
useDefaultExcludes：布尔类型，如果为true，则代表使用Ant风格路径默认排除文件列表。
除了name参数，其他参数都是可选的。excludes和includes使用的是Ant风格路径表达式。
unstash
取出之前stash的文件。
unstash步骤只有一个name参数，即stash时的唯一标识。通常stash与unstash步骤同时使用。以下是完整示例。
pipeline {
agent none
stages {
stage('stash') {
agent { label "master" }
steps {
script {
writeFile file: "a.txt", text: "$BUILD_NUMBER"
stash(name: "abc", include: "a.txt")
stage("unstash") {
agent { label "node2" }
steps {
script {
unstash("abc")
def content = readFile("a.txt")
echo "${content}"
stash步骤在master节点上执行，而unstash步骤在node2节点上执行
4.2.3、命令相关步骤
与命令相关的步骤其实是Pipeline：Nodes and Processes插件提供的步骤。由于它是Pipeline插件的一个组件，所以基本不需要单独安装。
执行shell命令。
sh步骤支持的参数有：
script：将要执行的shell脚本，通常在类UNIX系统上可以是多行脚本。
encoding：脚本执行后输出日志的编码，默认值为脚本运行所在系统的编码。
returnStatus：布尔类型，默认脚本返回的是状态码，如果是一个非零的状态码，则会引发pipeline执行失败。如果returnStatus参数为true，则不论状态码是什么，pipeline的执行都不会受影响。
returnStdout：布尔类型，如果为true，则任务的标准输出将作为步骤的返回值，而不是打印到构建日志中（如果有错误，则依然会打印到日志中）。除了script参数，其他参数都是可选的。
returnStatus与returnStdout参数一般不会同时使用，因为返回值只能有一个。如果同时使用，则只有returnStatus参数生效。
bat、powershell
bat步骤执行的是Windows的批处理命令。powershell步骤执行的是PowerShell脚本，支持3+版本。这两个步骤支持的参数与sh步骤的一样。
4.2.4、其他步骤
error
主动报错，中止当前pipeline。
error步骤的执行类似于抛出一个异常。它只有一个必需参数：message。通常省略参数：error（"there's an error"）。
使用预定义的工具。
如果在Global Tool Configuration（全局工具配置）中配置了工具，那么可以通过tool步骤得到工具路径。
tool步骤支持的参数有：
name：工具名称。
type（可选）：工具类型，指该工具安装类的全路径类名。
每个插件的type值都不一样，而且绝大多数插件的文档根本不写type值。除了到该插件的源码中查找，还有一种方法可以让我们快速找到type值，就是前往Jenkins pipeline代码片段生成器中生成该tool步骤的代码即可。
timeout
代码块超时时间。
为timeout步骤闭包内运行的代码设置超时时间限制。如果超时，将抛出一个org.jenkinsci.plugins.workflow.steps.FlowInterruptedException异常。timeout步骤支持如下参数：
time：整型，超时时间。
unit（可选）：时间单位，支持的值有NANOSECONDS、MICROSECONDS、MILLISECONDS、SECONDS、MINUTES（默认）、HOURS、DAYS。
activity（可选）：布尔类型，如果值为true，则只有当日志没有活动后，才真正算作超时。
waitUntil
等待条件满足。
不断重复waitUntil块内的代码，直到条件为true。waitUntil不负责处理块内代码的异常，遇到异常时直接向外抛出。waitUntil步骤最好与timeout步骤共同使用，避免死循环。示例如下：
retry
重复执行块
执行N次闭包内的脚本。如果其中某次执行抛出异常，则只中止本次执行，并不会中止整个retry的执行。同时，在执行retry的过程中，用户是无法中止pipeline的。
steps {
retry(20) {
script {
sh script: 'curl http://example', returnStatus: true
sleep
让pipeline休眠一段时间。
sleep步骤可用于简单地暂停pipeline，其支持的参数有：
time：整型，休眠时间。
unit（可选）：时间单位，支持的值有NANOSECONDS、MICROSECONDS、MILLISECONDS、SECONDS（默认）、MINUTES、HOURS、DAYS。
参考来源：https://www.jenkins.io/doc/book/pipeline/syntax/
