声明式流水线

声明式流水线是Jenkins 2.5之后添加到 Jenkins Pipeline中的,它在流水线系统之上提供了一种更简单,更容易理解的语法。

所有有效的声明式流水线必须包含在一个 pipeline 块中, 比如:

pipeline {

    /* insert Declarative Pipeline here */

}

在声明式流水线中有效的基本语句和表达式遵循与 Groovy的语法同样的规则, 有以下例外:

流水线顶层必须是一个 block, 特别地: pipeline { };

没有分号作为语句分隔符,每条语句都必须在自己的行上;

块只能由 节段, 指令, 步骤, 或赋值语句组成;

区块部分

声明式流水线中的区块通常包含一个或多个 指令 或 步骤。

Agent

agent 部分指定了整个流水线或特定的部分, 将会在Jenkins环境中执行的位置,这取决于 agent 区域的位置。该部分必须在 pipeline 块的顶层被定义, 但是 stage 级别的使用是可选的。

参数

为了支持作者可能有的各种各样的用例流水线, 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 ‘maven:3-alpine’ } 或

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)

pipeline {

    agent { docker ‘maven:3-alpine’ }

    stages {

        stage(‘Example Build’) {

            steps {

                sh ‘mvn -B clean verify’

            }

        }

    }

}

在一个给定名称和标签(maven:3-alpine)的新建的容器上执行定义在流水线中的所有步骤 。

阶段级别的 agent 部分

Jenkinsfile (Declarative Pipeline)

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 部分的步骤的执行取决于流水线或阶段的完成状态。

无论流水线或阶段的完成状态如何,都允许在 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)

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 指令用于连续交付过程的每个离散部分,比如构建, 测试, 和部署。

示例

Jenkinsfile (Declarative Pipeline)

pipeline {

    agent any

    stages {

        stage(‘Example’) {

            steps {

                echo ‘Hello World’

            }

        }

    }

}

stages 部分通常会遵循诸如 agent, options 等的指令。

steps

steps 部分在给定的 stage 指令中执行的定义了一系列的一个或多个steps。

示例

Jenkinsfile (Declarative Pipeline)

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 。

示例

Jenkinsfile (Declarative Pipeline)

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.

可用选项

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)

pipeline {

    agent any

    options {

        timeout(time: 1, unit: ‘HOURS’)

    }

    stages {

        stage(‘Example’) {

            steps {

                echo ‘Hello World’

            }

        }

    }

}

指定一个小时的全局执行超时, 在此之后,Jenkins 将中止流水线运行。

阶段选项

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)

pipeline {

    agent any

    stages {

        stage(‘Example’) {

            options {

                timeout(time: 1, unit: ‘HOURS’)

            }

            steps {

                echo ‘Hello World’

            }

        }

    }

}

指定 Example 阶段的执行超时时间, 在此之后,Jenkins 将中止流水线运行。

参数

parameters 指令提供了一个用户在触发流水线时应该提供的参数列表。这些用户指定参数的值可通过 params 对象提供给流水线步骤, 了解更多请参考示例。

可用参数

string

字符串类型的参数, 例如: parameters { string(name: ‘DEPLOY_ENV’, defaultValue: ‘staging’, description: ”) }

booleanParam

布尔参数, 例如: parameters { booleanParam(name: ‘DEBUG_BUILD’, defaultValue: true, description: ”) }

示例

Jenkinsfile (Declarative Pipeline)

pipeline {

    agent any

    parameters {

        string(name: ‘PERSON’, defaultValue: ‘Mr Jenkins’, description: ‘Who should I say hello to?’)

    }

    stages {

        stage(‘Example’) {

            steps {

                echo “Hello ${params.PERSON}”

            }

        }

    }

}

总结

Jenkins  Pipeline 有诸多的语法,上述列举了主要的区块指令,如需了解更多的关于Trigger, Input, When 等指令用法,大家可参见Jenkins 官方文档 和 逗点云的Pipeline 全解析系列课程 (https://ke.qq.com/course/458814?tuin=9239b190)



关注微信服务号,手机看文章
关注微信服务号,手机看文章