流水线语法
本节是建立在 流水线入门内容的基础上，而且，应当被当作一个参考。 对于在实际示例中如何使用流水线语法的更多信息, 请参阅本章在流水线插件的2.5版本中的 使用 Jenkinsfile部分, 流水线支持两种离散的语法，具体如下对于每种的优缺点, 参见语法比较。
正如 本章开始讨论的, 流水线最基础的部分是 “步骤”。基本上, 步骤告诉 Jenkins 要做什么，以及作为声明式和脚本化流水线语法的基本构建块。
对于可用步骤的概述, 请参考 流水线步骤引用，它包含了一个构建到流水线的步骤和 插件提供的步骤的全面的列表。
声明式流水线
声明式流水线是最近添加到 Jenkins 流水线的 [1]，它在流水线子系统之上提供了一种更简单，更有主见的语法。
所有有效的声明式流水线必须包含在一个 pipeline 块中, 比如:
pipeline {
/* insert Declarative Pipeline here */
}在声明式流水线中有效的基本语句和表达式遵循与 Groovy的语法同样的规则， 有以下例外:
- 流水线顶层必须是一个 block, 特别地:
pipeline { } - 没有分号作为语句分隔符，，每条语句都必须在自己的行上。
- 块只能由 节段, 指令, 步骤, 或赋值语句组成。 *属性引用语句被视为无参方法调用。 例如, input被视为 input()
节段
声明式流水线中的节段通常包含一个或多个 指令 或 步骤。
代理
agent 部分指定了整个流水线或特定的部分, 将会在Jenkins环境中执行的位置，这取决于 agent 区域的位置。该部分必须在 pipeline 块的顶层被定义, 但是 stage 级别的使用是可选的。
Required | Yes |
|---|---|
Parameters | Described below |
Allowed | In the top-level pipeline block and each stage block. |
参数
为了支持作者可能有的各种各样的用例流水线, agent 部分支持一些不同类型的参数。这些参数应用在pipeline块的顶层, 或 stage 指令内部。
- any
在任何可用的代理上执行流水线或阶段。例如:
agent any - none
当在
pipeline块的顶部没有全局代理， 该参数将会被分配到整个流水线的运行中并且每个stage部分都需要包含他自己的agent部分。比如:agent none - label
在提供了标签的 Jenkins 环境中可用的代理上执行流水线或阶段。 例如:
agent { label 'my-defined-label' } - node
agent { node { label 'labelName' } }和agent { label 'labelName' }一样, 但是node允许额外的选项 (比如customWorkspace)。 - docker
使用给定的容器执行流水线或阶段。该容器将在预置的 node上，或在匹配可选定义的
label参数上，动态的供应来接受基于Docker的流水线。docker也可以选择的接受args参数，该参数可能包含直接传递到docker run调用的参数, 以及alwaysPull选项, 该选项强制docker pull，即使镜像名称已经存在。 比如: agent { docker { image 'maven:3-alpine' label 'my-defined-label' args '-v /tmp:/tmp' } } - dockerfile
执行流水线或阶段, 使用从源代码库包含的
Dockerfile构建的容器。为了使用该选项，Jenkinsfile必须从多个分支流水线中加载, 或者加载 “Pipeline from SCM.” 通常，这是源代码仓库的根目录下的Dockerfile:agent { dockerfile true }. 如果在另一个目录下构建Dockerfile, 使用dir选项:agent { dockerfile {dir 'someSubDir' } }。如果Dockerfile有另一个名称, 你可以使用filename选项指定该文件名。你可以传递额外的参数到docker build ...使用additionalBuildArgs选项提交, 比如agent { dockerfile {additionalBuildArgs '--build-arg foo=bar' } }。 例如, 一个带有build/Dockerfile.build的仓库,期望一个构建参数version: agent { // Equivalent to "docker build -f Dockerfile.build --build-arg version=1.0.2 ./build/ dockerfile { filename 'Dockerfile.build' dir 'build' label 'my-defined-label' additionalBuildArgs '--build-arg version=1.0.2' } }
常见选项
有一些应用于两个或更多 agent 的实现的选项。他们不被要求，除非特别规定。
- label
一个字符串。该标签用于运行流水线或个别的
stage。该选项对node,docker和dockerfile可用,node要求必须选择该选项。 - customWorkspace
一个字符串。在自定义工作区运行应用了
agent的流水线或个别的stage, 而不是默认值。 它既可以是一个相对路径, 在这种情况下，自定义工作区会存在于节点工作区根目录下, 或者一个绝对路径。比如: agent { node { label 'my-defined-label' customWorkspace '/some/other/path' } } 该选项对node,docker和dockerfile有用 。 - reuseNode
一个布尔值, 默认为false。 如果是true, 则在流水线的顶层指定的节点上运行该容器, 在同样的工作区, 而不是在一个全新的节点上。这个选项对
docker和dockerfile有用, 并且只有当 使用在个别的stage的agent上才会有效。
示例
Jenkinsfile (Declarative Pipeline)
代码语言：javascript复制pipeline {
agent { docker 'maven:3-alpine' }
stages {
stage('Example Build') {
steps {
sh 'mvn -B clean verify'
}
}
}
}在一个给定名称和标签(maven:3-alpine)的新建的容器上执行定义在流水线中的所有步骤 。 | |
|---|---|
阶段级别的 agent 部分
Jenkinsfile (Declarative Pipeline)
代码语言：javascript复制pipeline {
agent none
stages {
stage('Example Build') {
agent { docker 'maven:3-alpine' }
steps {
echo 'Hello, Maven'
sh 'mvn --version'
}
}
stage('Example Test') {
agent { docker 'openjdk:8-jre' }
steps {
echo 'Hello, JDK'
sh 'java -version'
}
}
}
}在流水线顶层定义 agent none 确保 an Executor 没有被分配。 使用 agent none 也会强制 stage 部分包含他自己的 agent 部分。 | |
|---|---|
使用镜像在一个新建的容器中执行该阶段的该步骤。 | |
使用一个与之前阶段不同的镜像在一个新建的容器中执行该阶段的该步骤。 |
post
post 部分定义一个或多个steps ，这些阶段根据流水线或阶段的完成情况而 运行(取决于流水线中 post 部分的位置). post 支持以下 post-condition 块中的其中之一: always, changed, failure, success, unstable, 和 aborted。这些条件块允许在 post 部分的步骤的执行取决于流水线或阶段的完成状态。
Required | No |
|---|---|
Parameters | None |
Allowed | In the top-level pipeline block and each stage block. |
Conditions
always无论流水线或阶段的完成状态如何，都允许在post部分运行该步骤。changed只有当前流水线或阶段的完成状态与它之前的运行不同时，才允许在post部分运行该步骤。failure只有当前流水线或阶段的完成状态为”failure”，才允许在post部分运行该步骤, 通常web UI是红色。success只有当前流水线或阶段的完成状态为”success”，才允许在post部分运行该步骤, 通常web UI是蓝色或绿色。unstable只有当前流水线或阶段的完成状态为”unstable”，才允许在post部分运行该步骤, 通常由于测试失败,代码违规等造成。通常web UI是黄色。aborted只有当前流水线或阶段的完成状态为”aborted”，才允许在post部分运行该步骤, 通常由于流水线被手动的aborted。通常web UI是灰色。
示例
Jenkinsfile (Declarative Pipeline)
代码语言：javascript复制pipeline {
agent any
stages {
stage('Example') {
steps {
echo 'Hello World'
}
}
}
post {
always {
echo 'I will always say Hello again!'
}
}
}按照惯例, post 部分应该放在流水线的底部。 | |
|---|---|
Post-condition 块包含与 steps 部分相同的steps。 |
stages
包含一系列一个或多个 stage 指令, stages 部分是流水线描述的大部分”work” 的位置。 建议 stages 至少包含一个 stage 指令用于连续交付过程的每个离散部分,比如构建, 测试, 和部署。
Required | Yes |
|---|---|
Parameters | None |
Allowed | Only once, inside the pipeline block. |
示例
Jenkinsfile (Declarative Pipeline)
代码语言：javascript复制pipeline {
agent any
stages {
stage('Example') {
steps {
echo 'Hello World'
}
}
}
}stages 部分通常会遵循诸如 agent, options 等的指令。 | |
|---|---|
steps
steps 部分在给定的 stage 指令中执行的定义了一系列的一个或多个steps。
Required | Yes |
|---|---|
Parameters | None |
Allowed | Inside each stage block. |
示例
Jenkinsfile (Declarative Pipeline)
代码语言：javascript复制pipeline {
agent any
stages {
stage('Example') {
steps {
echo 'Hello World'
}
}
}
}steps 部分必须包含一个或多个步骤。
指令
environment
environment 指令制定一个 键-值对序列，该序列将被定义为所有步骤的环境变量，或者是特定于阶段的步骤， 这取决于 environment 指令在流水线内的位置。
该指令支持一个特殊的助手方法 credentials() ，该方法可用于在Jenkins环境中通过标识符访问预定义的凭证。对于类型为 “Secret Text”的凭证, credentials() 将确保指定的环境变量包含秘密文本内容。对于类型为 “SStandard username and password”的凭证, 指定的环境变量指定为 username:password ，并且两个额外的环境变量将被自动定义 :分别为 MYVARNAME_USR 和 MYVARNAME_PSW 。
Required | No |
|---|---|
Parameters | None |
Allowed | Inside the pipeline block, or within stage directives. |
示例
Jenkinsfile (Declarative Pipeline)
代码语言：javascript复制pipeline {
agent any
environment {
CC = 'clang'
}
stages {
stage('Example') {
environment {
AN_ACCESS_KEY = credentials('my-prefined-secret-text')
}
steps {
sh 'printenv'
}
}
}
}顶层流水线块中使用的 environment 指令将适用于流水线中的所有步骤。 | |
|---|---|
在一个 stage 中定义的 environment 指令只会将给定的环境变量应用于 stage 中的步骤。 | |
environment 块有一个 助手方法 credentials() 定义，该方法可以在 Jenkins 环境中用于通过标识符访问预定义的凭证。 |
options
options 指令允许从流水线内部配置特定于流水线的选项。 流水线提供了许多这样的选项, 比如 buildDiscarder,但也可以由插件提供, 比如 timestamps.
Required | No |
|---|---|
Parameters | None |
Allowed | Only once, inside the pipeline block. |
可用选项
- buildDiscarder
为最近的流水线运行的特定数量保存组件和控制台输出。例如:
options { buildDiscarder(logRotator(numToKeepStr: '1')) } - disableConcurrentBuilds
不允许同时执行流水线。 可被用来防止同时访问共享资源等。 例如:
options { disableConcurrentBuilds() } - overrideIndexTriggers
允许覆盖分支索引触发器的默认处理。 如果分支索引触发器在多分支或组织标签中禁用,
options { overrideIndexTriggers(true) }将只允许它们用于促工作。否则,options { overrideIndexTriggers(false) }只会禁用改作业的分支索引触发器。 - skipDefaultCheckout
在
agent指令中，跳过从源代码控制中检出代码的默认情况。例如:options { skipDefaultCheckout() } - skipStagesAfterUnstable
一旦构建状态变得UNSTABLE，跳过该阶段。例如:
options { skipStagesAfterUnstable() } - checkoutToSubdirectory
在工作空间的子目录中自动地执行源代码控制检出。例如:
options { checkoutToSubdirectory('foo') } - timeout
设置流水线运行的超时时间, 在此之后，Jenkins将中止流水线。例如:
options { timeout(time: 1, unit: 'HOURS') } - retry
在失败时, 重新尝试整个流水线的指定次数。 For example:
options { retry(3) } - timestamps
预谋所有由流水线生成的控制台输出，与该流水线发出的时间一致。 例如:
options { timestamps() }
Example
Jenkinsfile (Declarative Pipeline)
代码语言：javascript复制pipeline {
agent any
options {
timeout(time: 1, unit: 'HOURS')
}
stages {
stage('Example') {
steps {
echo 'Hello World'
}
}
}
}指定一个小时的全局执行超时, 在此之后，Jenkins 将中止流水线运行。 | |
|---|---|
一个完整的可用选项列表正在等待完成第 INFRA-1503次。 | |
|---|---|
阶段选项
stage 的 options 指令类似于流水线根目录上的 options 指令。然而， stage -级别 options 只能包括 retry, timeout, 或 timestamps 等步骤, 或与 stage 相关的声明式选项，如 skipDefaultCheckout。
在stage, options 指令中的步骤在进入 agent 之前被调用或在 when 条件出现时进行检查。
可选的阶段选项
- skipDefaultCheckout
在
agent指令中跳过默认的从源代码控制中检出代码。例如:options { skipDefaultCheckout() } - timeout
设置此阶段的超时时间, 在此之后， Jenkins 会终止该阶段。 例如:
options { timeout(time: 1, unit: 'HOURS') } - retry
在失败时, 重试此阶段指定次数。 例如:
options { retry(3) } - timestamps
预谋此阶段生成的所有控制台输出以及该行发出的时间一致。例如:
options { timestamps() }
示例
Jenkinsfile (Declarative Pipeline)
代码语言：javascript复制pipeline {
agent any
stages {
stage('Example') {
options {
timeout(time: 1, unit: 'HOURS')
}
steps {
echo 'Hello World'
}
}
}
}指定 Example 阶段的执行超时时间, 在此之后，Jenkins 将中止流水线运行。
