笔者是独立翻译实验，不允许转载
Pipeline Syntax
本节基于入门中介绍的信息, 应仅作为参考进行处理。有关如何在实际示例中使用Pipeline语法的详细信息, 请参阅本章的 Jenkinsfile 部分。在Pipeline插件的2.5 版中, Pipeline支持两个离散的语法, 下面是详细的。对于每个优点和缺点, 请参见语法比较。
正如在入门中所讨论的, Pipeline最基本的部分是步骤step。基本上, 步骤step告诉Jenkins该做什么, 并作为声明式和脚本式Pipeline语法的基本构造块。
有关可用步骤的概述, 请参阅Pipeline步骤参考, 其中包含内置的步骤的全面列表以及插件提供的步骤。
Declarative Pipeline
声明式Pipeline是Jenkins Pipeline的一个相对最近的加法, 它在Pipeline子系统的顶部提供了一种更简化和自以为是的语法。
所有有效的声明Pipeline必须包含在Pipeline块中, 例如:
在声明性Pipeline中有效的基本语句和表达式遵循与 Groovy 语法相同的规则, 但有以下例外情况:
- Pipeline的 top-level 必须是一个块, 特别是: pipeline {}
- 没有分号作为语句分隔符。每个语句都必须在自己的行上
- 块必须由节、指令、步骤或赋值语句组成。
- 属性引用语句被视为参数方法调用。例如, 输入被视为输入 ()
Sections
声明性Pipeline中的节通常包含一个或多个指令Directive或步骤steps。
agent
代理部分指定在Jenkins环境中执行整个Pipeline或特定阶段的位置, 具体取决于代理部分的放置位置。该节必须在Pipeline块内的 top-level 中定义, 但阶段级别的时候使用是可选的。
| Required | Yes |
| Parameters | Described below |
| Allowed | In the top-level pipeline block and each stage block |
Parameters
为了支持Pipeline作者可能有的各种用例, 代理部分支持几种不同类型的参数。这些参数可在Pipeline块的 top-level 或每个阶段指令中应用。
any
在任何可用的代理上执行Pipeline或阶段。例如: 代理任何agent any。
none
当在Pipeline块的 top-level 应用时, 将不会为整个Pipeline运行分配全局代理, 并且每个阶段部分都需要包含其自己的代理部分。例如: 代理无agent none。
label
使用所提供的标签, 在Jenkins环境中可用的代理上执行Pipeline或stage。例如: 代理 {标签为‘my-defined-label’}。
node
agent{ node {label ‘labelName’}}}和agent { label ‘labelName’}一样，node允许附加的选项，例如customWorkspace。
docker
对给定的容器执行Pipeline或stage, 在预先配置为接受 Docker-based Pipeline的节点上或在与可选的标签参数匹配的节点上动态调配。Docker还可以选择接受参数, 其中可能包含直接传递到docker运行调用的参数, 以及一个 alwaysPull 选项, 即使图像名称已存在, 也会强制执行docker。例如 agent { docker ‘maven：3-alpine’}
dockerfile
使用源存储库中包含的Dockerfile生成的容器来执行Pipeline或stage。要想使用这个选项，Jenkinsfile必须通过Multibranch Pipeline或者Pipeline from SCM。通常这是源存储库根目录中的 Dockerfile：agent { dockerfile true }。如果在另一个目录中生成Dockerfile, 请使用dir选项：agent { dockerfile { dir ‘somSubDir’} }。您可以用additionalBuildArgs选项传递参数到docker build……命令中，像agent { dockerfile { additionalBuildArgs ‘–build-arg foo=bar’ } }。
Common Options
这些是可以应用两个或更多agent实现的几个选项。除非明确说明, 否则不是必需的。
Label
一个字符串。要在其上运行Pipeline或单个stage的标签。
此选项对于node，docker和dockerfile有效，并且对node是必需的。
customWorkspace
一个字符串。运行Pipeline或单个stage，此agent在该自定义工作区中应用, 而不是默认。它可以是相对路径, 在这种情况下, 自定义工作区将位于节点的工作区根目录下, 或者是绝对路径。例如：
此选项对于node，docker和dockerfile有效。
reuseNode
布尔值, 默认为 false。如果为 true, 则在Pipeline的 top-level 上指定的节点上, 在同一工作区中, 而不是在新节点上运行容器。
此选项对docker和dockerfile有效, 并且仅在用于单个stage的agent时具有效果。
Example
①在新创建的给定名称和标记(maven:3-alpine)容器中, 执行此Pipeline中定义的所有步骤。
Stage-level agent部分
在Pipeline的 top-level 定义agent none, 确保不会不必要地分配执行器。使用agent none 还强制每个stage部分包含其自己的agent部分。
使用此image在新创建的容器中执行此阶段中的步骤。
使用上一个阶段的不同image, 在新创建的容器中执行此阶段中的步骤。
Post
post 部分定义将在Pipeline运行或阶段结束时运行的操作。post 部分中支持许多条件块: 始终(always)、已更改(changed)、失败(failure)、成功(success)、不稳定(unstable)和中止(aborted)。这些块允许在Pipeline运行或阶段的末尾执行步骤, 具体取决于管线的状态。
| Required | No |
|---|---|
| Parameters | None |
| Allowed | In the top-level pipeline block and each stage block |
Conditions
always无论Pipeline运行的完成状态如何, 都将运行。
changed仅当当前Pipeline运行与以前完成的Pipeline的状态不同时才运行。
failure只有在当前Pipeline出现故障状态时才运行, 通常在 web UI 中用红色指示表示。
success只有在当前Pipeline具有成功状态时才运行, 通常在 web UI 中用蓝色或绿色表示。
unstable只有在当前Pipeline的状态不稳定时才运行, 通常是由测试失败、代码违规等引起的。通常用黄色指示在 web UI 中表示。
aborted仅在当前Pipeline具有中止状态时运行, 通常是由于Pipeline被手动中止。通常在 web UI 中用灰色指示表示。
Example
通常情况下, post部分应放置在Pipeline的末尾。
Post-condition块包含与steps部分相同的steps。
stages
包含一个或多个stage指令的序列, stages部分是Pipeline所描述的大部分”work”的位置。至少建议stages对连续传递过程中的每个离散部分 ，如生成、测试和部署， 至少包含一个阶段指令。
| Required | Yes |
|---|---|
| Parameters | None |
| Allowed | Only once, inside the pipeline block |
Example
- stage部分通常遵循指令, 如代理agent、选项options等。
steps
steps部分在指定的stage指令中定义一系列一个或多个将要执行的steps。
| Required | Yes |
|---|---|
| Parameters | None |
| Allowed | inside each stage block |
Example
- steps部分包含一个或多个steps。
Directives
environment
环境environment指令指定一个键值对序列, 它将被定义为所有steps的环境变量, 或特定阶段的steps, 具体取决于环境environment指令在Pipeline中的位置。
此指令支持一种特殊的方法credentials(), 可用于通过Jenkins环境中的标识符来访问预定义的凭据。对于类型为机密文本的凭据, credentials()方法将确保指定的环境变量包含秘密文本内容。对于类型为标准用户名和密码的凭据, 指定的环境变量将被设置为用户名: 密码和另外两个环境变量将被自动定义：MYVARNAME_USR和MYVARNAME_PSW。
| Required | No |
|---|---|
| Parameters | None |
| Allowed | inside the pipeline block, or within stage directives |
Example
- top-level Pipeline块中使用的environment指令将应用于Pipeline中的所有步骤。
- 在stage中定义的environment指令只将给定的环境变量应用于stage中的步骤。
- environment块具有定义的帮助方法credentials() 可用于通过Jenkins环境中的标识符来访问预定义的凭据。
Options
options指令允许在管线本身内配置Pipeline特定的选项。Pipeline提供了许多这些选项, 如buildDiscarder, 但它们也可能由插件提供, 如时间戳timestamps。| Required | No |
|---|---|
| Parameters | None |
| Allowed | Only Once, inside the pipeline block |
#### Available Options
###### buildDiscarder
持久性工件(Persist artifacts)和控制台输出的特定数量的最近Pipeline运行。例如：options { buildDiscarder(logRotator(numToKeepStr: ‘1’)) }。
###### disableConcurrentBuilds
不允许并发执行Pipeline。可用于防止同时访问共享资源等。例如：options { disableConcurrentBuilds() }。
###### overrideIndexTriggers
允许重写分支索引触发器的默认处理。如果在 multibranch 或组织标签中禁用了分支索引触发器, 则options {overrideIndexTriggers (true)}将仅为该作业启用它们。否则,options {overrideIndexTriggers (false)}将仅禁用此作业的分支索引触发器。
###### skipDefaultCheckout
在agent指令中, 在默认情况下跳过源代码管理中的签出。例如: options {skipDefaultCheckout ()}。
###### skipStageAfterUnstable
一旦生成状态不稳定, 就跳过各个阶段。例如: options {skipStagesAfterUnstable ()}。
###### timeout
设置Pipeline运行的超时期限, 之后Jenkins应中止Pipeline。例如: options { timeout(time: 1, unit: ‘HOURS’) }。
###### retry
失败时, 请在指定的次数内重试整个管线。例如: options { retry(3) }。
###### timestamps
将管线所生成的所有控制台输出与发出该行的时间放在一起。例如: options { timestamps() }。
###### Examples
* 指定一个小时的全局执行超时, 之后Jenkins将中止Pipeline运行。
提示：可供选择的综合清单尚待INFRA-1503完成。
#### parameters
参数parameters指令提供用户在触发Pipeline时应提供的参数列表。这些用户指定的参数的值可通过参数params对象提供给Pipeline steps, 请参阅]示例中的特定用法。
| Required | No |
|---|---|
| Parameters | None |
| Allowed | Only Once, inside the pipeline block |
#### Available Parameters
###### string
字符串类型参数，例如：parameters { string(name: ‘DEPLOY_ENV’, defaultValue: ‘staging’, description: ‘’) }
booleanParam
布尔值参数，例如：parameters { booleanParam(name: ‘DEBUG_BUILD’, defaultValue: true, description: ‘’) }
Examples
提示：可供选择的综合清单尚待INFRA-1503完成。
Triggers
triggers指令定义了Pipeline应 re-triggered 的自动方式。对于与源 (如 GitHub 或 BitBucket) 集成的管线, 可能不需要triggers, 因为 webhooks-based 集成可能已经存在。当前可用的触发器有 cron、pollSCM 和upstream。
| Required | No |
|---|---|
| Parameters | None |
| Allowed | Only Once, inside the pipeline block |
Cron
接受一个 cron 样式的字符串来定义Pipeline应 re-triggered 的规则间隔。例如：triggers { cron(‘H */4 1-5’) }。
pollSCM
接受一个 cron 样式的字符串来定义一个规则的时间间隔, 詹金斯应该检查新的源更改。例如：triggers { pollSCM(‘H */4 1-5’) }。
upstream
接受一个逗号分隔的作业字符串和一个阈值。当字符串中的任何作业以最小阈值结束时, 管线将被 re-triggered。例如：triggers { upstream(upstreamProjects: ‘job1,job2’, threshold: hudson.model.Result.SUCCESS) }。
提示：pollSCM触发器只在Jenkins版本2.22或者以后有效。。
Example
stage
stage指令进入stages部分，应该包含一个steps部分，一个可选的agent部分，或者其它特殊平台指令。实际上, Pipeline所完成的所有工作都将在一个或多个stage指令中进行包装。
| Required | At least one |
|---|---|
| Parameters | One mandatory parameter, a string for the name of the stage. |
| Allowed | Inside the stages section |
Example
tools
定义用于自动和放置PATH的工具的部分。如果agent none指定, 则忽略此项。
| Required | No |
|---|---|
| Parameters | None |
| Allowed | Inside the pipeline block or a stage block. |
Supported Tools
maven
jdk
gradle
Example
- 工具名称必须在Jenkins中预先配置：Manage Jenkins → Global Tool Configuration。
when
when指令允许Pipeline根据给定的条件来决定是否执行stage。when指令必须包含至少一个条件。如果when指令包含多个条件时, 所有子条件必须返回 true 才能执行阶段。这与子条件嵌套在allof条件下的情况相同 (请参见下面的示例)。
可以使用嵌套条件构建更复杂的条件结构: not、allOf或anyOf。嵌套条件可以嵌套到任意深度。
| Required | No |
|---|---|
| Parameters | None |
| Allowed | Inside a stage directive |
Built-in Conditions
branch
在所构建的分支与给定的分支模式匹配时执行stage，例如：when { branch ‘master’ }。注意：这仅仅在multibranch Pipeline有效。
environment
特殊环境变量被设置给定值以后，执行stage，例如：when { environment name: ‘DEPLOY_TO’, value: ‘production’ }。
expression
当指定的Groovy表达式计算为真时执行stage，例如：when { expression { return params.DEBUG_BUILD } }。
not
当嵌套条件为假时执行stage。例如：when { not { branch ‘master’ } }。
allOf
当所有嵌套条件为真时执行stage。必须包含至少一个条件，例如：when { allOf { branch ‘master’; environment name: ‘DEPLOY_TO’, value: ‘production’ } }。
anyOf
当至少一个前条件为真时执行stage。必须包含至少一个条件，例如：when { anyOf { branch ‘master’; branch ‘staging’ } }。
Examples
Parallel
申明式Pipeline中有可能在里面申明许多嵌套的stages，这些stage将被并行执行。请注意, 一个stage必须有一个且只有一个steps或parallel。嵌套stage本身不能包含进一步的parallel stages, 但其他的行为与其他stages相同。包含parallel的任何stage都不能包含agent或tools, 因为没有steps，他们并不具有相关性。
此外, 您可以强制您的parallel stage全部被中止, 当其中一个失败, 通过增加’failFast true’到包含parallel的stage。
Example
Steps
声明式Pipeline可能会使用Pipeline steps reference中记录的所有可用steps, 其中包含一个完整的steps列表, 其中添加了仅在声明性Pipeline中支持的下面列出的steps。
script
script step采用了一个脚本化的Pipeline块, 并在声明性Pipeline中执行。对于大多数用例, 脚本步骤在声明性Pipeline中应该是不必要的, 但它可以提供一个有用的”escape hatch”。 Script块和/或复杂性的脚本script块应该改为]共享库。
Example
Scripted Pipeline
脚本化Pipeline (如声明式Pipeline) 建立在底层管线子系统的顶部。不像声明式, 脚本Pipeline是有效的通用 DSL 内置的 Groovy。Groovy 语言提供的大多数功能都可供脚本Pipeline用户使用, 这意味着它可以是一个非常富有表现力和灵活性的工具, 可以创作连续的交付Pipeline。
Flow Control
脚本化Pipeline从 Jenkinsfile 的顶部向下连续执行, 就像 Groovy 或其他语言中的大多数传统脚本一样。因此, 提供流控制依赖于 Groovy 表达式, 如 if/else 条件, 例如:
通过 Groovy 的异常处理支持, 可以管理另一种脚本式Pipeline流控制。当steps因任何原因而失败时, 它们抛出一个异常。错误处理行为必须使用 Groovy 中的 try/catch/finally 块, 例如:
Steps
正如在入门中所讨论的, Pipeline最基本的部分是”step”。从根本上讲, step告诉Jenkins该做什么, 并充当声明性和脚本化Pipeline语法的基本构建基块。
脚本Pipeline不引入特定于其语法的任何steps; Pipeline Steps reference, 其中包含Pipeline和插件提供的steps的全面列表。
Differences from plain Groovy
为了提供耐用性, 这意味着运行Pipeline可以生存的Jenkins master重启, 脚本Pipeline必须序列化数据回master。由于这一设计要求, 一些 Groovy 成语如collection.each { item -> /* perform operation */ }不完全受支持。有关详细信息, 请参阅 JENKINS-27421 和 JENKINS-26481。
Syntax Comparison
当Jenkins Pipeline首次创建时, Groovy 被选为基础。Jenkins长期推出了一个嵌入式的 Groovy 引擎, 为管理员和用户提供高级脚本功能。此外, Jenkins Pipeline的实现基于 Groovy 的基础上, 建立现在称为”脚本Pipeline” DSL。
由于它是一个功能完备的编程环境, 因此脚本化的管道为Jenkins用户提供了大量的灵活性和可扩展性。对于给定团队的所有成员来说, Groovy 学习曲线通常并不可取, 因此创建了声明性Pipeline, 为创作Jenkins Pipeline提供了更简单、更可用的语法。
两者基本上是相同的Pipeline子系统下面。它们都是作为”代码即管道(Pipeline as code)”的持久实现。他们都能够使用Pipeline内置的steps或由插件提供。都可以利用共享库。
然而他们不同的地方在句法和灵活性。声明性限制用户使用更严格和预先定义的结构, 使其成为更简单的连续传递Pipeline的理想选择。脚本提供的限制很少, 因为结构和语法的唯一限制往往是由 Groovy 本身定义的, 而不是任何特定于Pipeline的系统, 这使得它成为了电力用户和更复杂需求的理想选择。顾名思义, 声明性Pipeline是鼓励一个声明式编程模型。而脚本化的Pipeline遵循更命令性的编程模型。