对应英文文档:https://jenkins.io/doc/book/pipeline/syntax/
本系列主贴直达：https://testerhome.com/topics/11265

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

<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

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, 请参阅 [] 示例](https://jenkins.io/doc/book/pipeline/syntax/#parameters-example) 中的特定用法。

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 块应该改为 [] 共享库](https://jenkins.io/doc/book/pipeline/shared-libraries/)。

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 遵循更命令性的编程模型。

本系列主贴直达：https://testerhome.com/topics/11265