对应英文文档:https://jenkins.io/doc/book/pipeline/syntax/
本系列主贴直达：https://testerhome.com/topics/11265
本节基于入门中介绍的信息, 应仅作为参考进行处理。有关如何在实际示例中使用 Pipeline 语法的详细信息, 请参阅本章的 Jenkinsfile 部分。在 Pipeline 插件的 2.5 版中, Pipeline 支持两个离散的语法, 下面是详细的。对于每个优点和缺点, 请参见语法比较。
正如在入门中所讨论的, Pipeline 最基本的部分是步骤 step。基本上, 步骤 step 告诉 Jenkins 该做什么, 并作为声明式和脚本式 Pipeline 语法的基本构造块。
有关可用步骤的概述, 请参阅 Pipeline 步骤参考, 其中包含内置的步骤的全面列表以及插件提供的步骤。
声明式 Pipeline 是 Jenkins Pipeline 的一个相对最近的加法, 它在 Pipeline 子系统的顶部提供了一种更简化和自以为是的语法。
所有有效的声明 Pipeline 必须包含在 Pipeline 块中, 例如:
在声明性 Pipeline 中有效的基本语句和表达式遵循与 Groovy 语法相同的规则, 但有以下例外情况:
声明性 Pipeline 中的节通常包含一个或多个指令 Directive 或步骤 steps。
代理部分指定在 Jenkins 环境中执行整个 Pipeline 或特定阶段的位置, 具体取决于代理部分的放置位置。该节必须在 Pipeline 块内的 top-level 中定义, 但阶段级别的时候使用是可选的。
| Required | Yes |
| Parameters | Described below |
| Allowed | In the top-level pipeline block and each stage block |
为了支持 Pipeline 作者可能有的各种用例, 代理部分支持几种不同类型的参数。这些参数可在 Pipeline 块的 top-level 或每个阶段指令中应用。
在任何可用的代理上执行 Pipeline 或阶段。例如: 代理任何 agent any。
当在 Pipeline 块的 top-level 应用时, 将不会为整个 Pipeline 运行分配全局代理, 并且每个阶段部分都需要包含其自己的代理部分。例如: 代理无 agent none。
使用所提供的标签, 在 Jenkins 环境中可用的代理上执行 Pipeline 或 stage。例如: 代理 {标签为 ‘my-defined-label’}。
agent{ node {label ‘labelName’}}}和 agent { label ‘labelName’}一样，node 允许附加的选项，例如 customWorkspace。
对给定的容器执行 Pipeline 或 stage, 在预先配置为接受 Docker-based Pipeline 的节点上或在与可选的标签参数匹配的节点上动态调配。Docker 还可以选择接受参数, 其中可能包含直接传递到 docker 运行调用的参数, 以及一个 alwaysPull 选项, 即使图像名称已存在, 也会强制执行 docker。例如 agent { docker ‘maven：3-alpine’}
使用源存储库中包含的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' } }。
这些是可以应用两个或更多 agent 实现的几个选项。除非明确说明, 否则不是必需的。
一个字符串。要在其上运行 Pipeline 或单个 stage 的标签。
此选项对于 node，docker 和 dockerfile 有效，并且对 node 是必需的。
一个字符串。运行 Pipeline 或单个 stage，此 agent 在该自定义工作区中应用, 而不是默认。它可以是相对路径, 在这种情况下, 自定义工作区将位于节点的工作区根目录下, 或者是绝对路径。例如：
此选项对于 node，docker 和 dockerfile 有效。
布尔值, 默认为 false。如果为 true, 则在 Pipeline 的 top-level 上指定的节点上, 在同一工作区中, 而不是在新节点上运行容器。
此选项对docker和dockerfile有效, 并且仅在用于单个stage的agent时具有效果。
<img src="http://oow5aq3zy.bkt.clouddn.com/image/pp7/4.png/"
①在新创建的给定名称和标记 (maven:3-alpine) 容器中, 执行此 Pipeline 中定义的所有步骤。
Stage-level agent部分
<img src="http://oow5aq3zy.bkt.clouddn.com/image/pp7/5.png/"
在 Pipeline 的 top-level 定义 agent none, 确保不会不必要地分配执行器。使用 agent none 还强制每个 stage 部分包含其自己的 agent 部分。
使用此 image 在新创建的容器中执行此阶段中的步骤。
使用上一个阶段的不同 image, 在新创建的容器中执行此阶段中的步骤。
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 |
always
无论 Pipeline 运行的完成状态如何, 都将运行。
changed
仅当当前 Pipeline 运行与以前完成的 Pipeline 的状态不同时才运行。
failure
只有在当前 Pipeline 出现故障状态时才运行, 通常在 web UI 中用红色指示表示。
success
只有在当前 Pipeline 具有成功状态时才运行, 通常在 web UI 中用蓝色或绿色表示。
unstable
只有在当前 Pipeline 的状态不稳定时才运行, 通常是由测试失败、代码违规等引起的。通常用黄色指示在 web UI 中表示。
aborted
仅在当前 Pipeline 具有中止状态时运行, 通常是由于 Pipeline 被手动中止。通常在 web UI 中用灰色指示表示。
通常情况下, post 部分应放置在 Pipeline 的末尾。
Post-condition 块包含与 steps 部分相同的 steps。
包含一个或多个 stage 指令的序列, stages 部分是 Pipeline 所描述的大部分” work” 的位置。至少建议 stages 对连续传递过程中的每个离散部分 ，如生成、测试和部署， 至少包含一个阶段指令。
| Required | Yes |
|---|---|
| Parameters | None |
| Allowed | Only once, inside the pipeline block |
steps 部分在指定的 stage 指令中定义一系列一个或多个将要执行的 steps。
| Required | Yes |
|---|---|
| Parameters | None |
| Allowed | inside each stage block |
环境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 |
options指令允许在管线本身内配置 Pipeline 特定的选项。Pipeline 提供了许多这些选项, 如buildDiscarder, 但它们也可能由插件提供, 如时间戳timestamps。
| Required | No |
|---|---|
| Parameters | None |
| Allowed | Only Once, inside the pipeline block |
持久性工件 (Persist artifacts) 和控制台输出的特定数量的最近 Pipeline 运行。例如：options { buildDiscarder(logRotator(numToKeepStr: '1')) }。
不允许并发执行 Pipeline。可用于防止同时访问共享资源等。例如：options { disableConcurrentBuilds() }。
允许重写分支索引触发器的默认处理。如果在 multibranch 或组织标签中禁用了分支索引触发器, 则options {overrideIndexTriggers (true)}将仅为该作业启用它们。否则,options {overrideIndexTriggers (false)}将仅禁用此作业的分支索引触发器。
在 agent 指令中, 在默认情况下跳过源代码管理中的签出。例如: options {skipDefaultCheckout ()}。
一旦生成状态不稳定, 就跳过各个阶段。例如: options {skipStagesAfterUnstable ()}。
设置 Pipeline 运行的超时期限, 之后 Jenkins 应中止 Pipeline。例如: options { timeout(time: 1, unit: 'HOURS') }。
失败时, 请在指定的次数内重试整个管线。例如: options { retry(3) }。
将管线所生成的所有控制台输出与发出该行的时间放在一起。例如: options { timestamps() }。
参数parameters指令提供用户在触发 Pipeline 时应提供的参数列表。这些用户指定的参数的值可通过参数params对象提供给 Pipeline steps, 请参阅 [] 示例](https://jenkins.io/doc/book/pipeline/syntax/#parameters-example) 中的特定用法。
| Required | No |
|---|---|
| Parameters | None |
| Allowed | Only Once, inside the pipeline block |
字符串类型参数，例如：parameters { string(name: 'DEPLOY_ENV', defaultValue: 'staging', description: '') }
布尔值参数，例如：parameters { booleanParam(name: 'DEBUG_BUILD', defaultValue: true, description: '') }
提示：可供选择的综合清单尚待INFRA-1503完成。
triggers指令定义了 Pipeline 应 re-triggered 的自动方式。对于与源 (如 GitHub 或 BitBucket) 集成的管线, 可能不需要triggers, 因为 webhooks-based 集成可能已经存在。当前可用的触发器有 cron、pollSCM 和upstream。
| Required | No |
|---|---|
| Parameters | None |
| Allowed | Only Once, inside the pipeline block |
接受一个 cron 样式的字符串来定义 Pipeline 应 re-triggered 的规则间隔。例如：triggers { cron('H */4 * * 1-5') }。
接受一个 cron 样式的字符串来定义一个规则的时间间隔, 詹金斯应该检查新的源更改。例如：triggers { pollSCM('H */4 * * 1-5') }。
接受一个逗号分隔的作业字符串和一个阈值。当字符串中的任何作业以最小阈值结束时, 管线将被 re-triggered。例如：triggers { upstream(upstreamProjects: 'job1,job2', threshold: hudson.model.Result.SUCCESS) }。
提示：pollSCM 触发器只在 Jenkins 版本 2.22 或者以后有效。。
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 |
定义用于自动和放置PATH的工具的部分。如果agent none指定, 则忽略此项。
| Required | No |
|---|---|
| Parameters | None |
| Allowed | Inside the pipeline block or a stage block. |
when指令允许 Pipeline 根据给定的条件来决定是否执行 stage。when指令必须包含至少一个条件。如果when指令包含多个条件时, 所有子条件必须返回 true 才能执行阶段。这与子条件嵌套在allof条件下的情况相同 (请参见下面的示例)。
可以使用嵌套条件构建更复杂的条件结构: not、allOf或anyOf。嵌套条件可以嵌套到任意深度。
| Required | No |
|---|---|
| Parameters | None |
| Allowed | Inside a stage directive |
在所构建的分支与给定的分支模式匹配时执行 stage，例如：when { branch 'master' }。注意：这仅仅在 multibranch Pipeline 有效。
特殊环境变量被设置给定值以后，执行 stage，例如：when { environment name: 'DEPLOY_TO', value: 'production' }。
当指定的 Groovy 表达式计算为真时执行 stage，例如：when { expression { return params.DEBUG_BUILD } }。
当嵌套条件为假时执行 stage。例如：when { not { branch 'master' } }。
当所有嵌套条件为真时执行 stage。必须包含至少一个条件，例如：when { allOf { branch 'master'; environment name: 'DEPLOY_TO', value: 'production' } }。
当至少一个前条件为真时执行 stage。必须包含至少一个条件，例如：when { anyOf { branch 'master'; branch 'staging' } }。
申明式 Pipeline 中有可能在里面申明许多嵌套的 stages，这些 stage 将被并行执行。请注意, 一个 stage 必须有一个且只有一个steps或parallel。嵌套 stage 本身不能包含进一步的parallel stages, 但其他的行为与其他stages相同。包含parallel的任何 stage 都不能包含agent或tools, 因为没有steps，他们并不具有相关性。
此外, 您可以强制您的parallel stage全部被中止, 当其中一个失败, 通过增加’failFast true’ 到包含parallel的stage。
声明式 Pipeline 可能会使用Pipeline steps reference中记录的所有可用 steps, 其中包含一个完整的 steps 列表, 其中添加了仅在声明性 Pipeline 中支持的下面列出的 steps。
script step 采用了一个脚本化的 Pipeline 块, 并在声明性 Pipeline 中执行。对于大多数用例, 脚本步骤在声明性 Pipeline 中应该是不必要的, 但它可以提供一个有用的” escape hatch”。 Script 块和/或复杂性的脚本 script 块应该改为 [] 共享库](https://jenkins.io/doc/book/pipeline/shared-libraries/)。
脚本化 Pipeline (如声明式 Pipeline) 建立在底层管线子系统的顶部。不像声明式, 脚本 Pipeline 是有效的通用 DSL 内置的 Groovy。Groovy 语言提供的大多数功能都可供脚本 Pipeline 用户使用, 这意味着它可以是一个非常富有表现力和灵活性的工具, 可以创作连续的交付 Pipeline。
脚本化 Pipeline 从 Jenkinsfile 的顶部向下连续执行, 就像 Groovy 或其他语言中的大多数传统脚本一样。因此, 提供流控制依赖于 Groovy 表达式, 如 if/else 条件, 例如:
通过 Groovy 的异常处理支持, 可以管理另一种脚本式 Pipeline 流控制。当 steps 因任何原因而失败时, 它们抛出一个异常。错误处理行为必须使用 Groovy 中的 try/catch/finally 块, 例如:
正如在入门中所讨论的, Pipeline 最基本的部分是” step”。从根本上讲, step 告诉 Jenkins 该做什么, 并充当声明性和脚本化 Pipeline 语法的基本构建基块。
脚本 Pipeline 不引入特定于其语法的任何 steps; Pipeline Steps reference, 其中包含 Pipeline 和插件提供的 steps 的全面列表。
为了提供耐用性, 这意味着运行 Pipeline 可以生存的 Jenkins master 重启, 脚本 Pipeline 必须序列化数据回 master。由于这一设计要求, 一些 Groovy 成语如collection.each { item -> /* perform operation */ }不完全受支持。有关详细信息, 请参阅 JENKINS-27421 和 JENKINS-26481。
当 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 遵循更命令性的编程模型。
本系列主贴直达：https://testerhome.com/topics/11265
