阅读(1808) 赞(10)

Pipeline 语法

2017-08-17 17:54:58 更新

本节基于“ 入门指南”中介绍的信息，并应作为参考。有关如何在实际示例中使用Pipeline语法的更多信息，请参阅本章的Jenkinsfile部分。从Pipeline插件2.5版开始，Pipeline支持两种离散语法，详细说明如下。对于每个的利弊，请参阅语法比较（下文中）。

如“ 入门指南 ”所述，Pipeline最基本的部分是“步骤”。基本上，步骤告诉Jenkins 要做什么，并且作为Declarative和Scripted Pipeline语法的基本构建块。

有关可用步骤的概述，请参阅 Pipeline步骤参考（下文中），其中包含Pipeline内置的完整列表以及插件提供的步骤。

声明Pipeline

声明性Pipeline是Jenkins Pipeline 的一个相对较新的补充，它在Pipeline子系统之上提出了一种更为简化和有意义的语法。

所有有效的声明性Pipeline必须包含在一个pipeline块内，例如：

pipeline {
    /* insert Declarative Pipeline here */
}

声明性Pipeline中有效的基本语句和表达式遵循与Groovy语法相同的规则，但有以下例外：

Pipeline的顶层必须是块，具体来说是：pipeline { }
没有分号作为语句分隔符。每个声明必须在自己的一行
块只能包含章节，指令，步骤或赋值语句。
属性引用语句被视为无参数方法调用。所以例如，输入被视为input（）

Sections

声明性Pipeline中的部分通常包含一个或多个指令或步骤。

agent

该agent部分指定整个Pipeline或特定阶段将在Jenkins环境中执行的位置，具体取决于该agent 部分的放置位置。该部分必须在pipeline块内的顶层定义，但阶段级使用是可选的。

需要	是
参数	如下面所描述的
允许	在顶级`pipeline`块和每个`stage`块中。

参数

为了支持作者可能有的各种各样的pipeline用例, agent 部分支持一些不同类型的参数。这些参数应用在`pipeline`块的顶层, 或 stage 指令内部。

any

在任何可用的代理上执行Pipeline或stage。例如：agent any

none

当在pipeline块的顶层应用时，将不会为整个Pipeline运行分配全局代理，并且每个stage部分将需要包含其自己的agent部分。例如：agent none

label

使用提供的标签在Jenkins环境中可用的代理上执行Pipeline或阶段性执行。例如：agent { label 'my-defined-label' }

node

agent { node { label 'labelName' } }行为相同 agent { label 'labelName' }，但node允许其他选项（如customWorkspace）。

docker

执行Pipeline，或阶段执行，用给定的容器将被动态地供应一个节点预先配置成接受基于Docker-based Pipelines，或匹配的任选定义的节点上 label的参数。 docker还可以接受一个args可能包含直接传递给docker run调用的参数的参数。例如：agent { docker 'maven:3-alpine' }或

agent {
    docker {
        image 'maven:3-alpine'
        label 'my-defined-label'
        args  '-v /tmp:/tmp'
    }
}

dockerfile: 使用从Dockerfile源存储库中包含的容器构建容器来执行Pipeline或阶段性执行。为了使用此选项，Jenkinsfile必须从多分支Pipeline或“Pipeline从SCM”加载。通常这是Dockerfile源库的根源：agent { dockerfile true }。如果Dockerfile在另一个目录中建立，请使用以下dir选项：agent { dockerfile { dir 'someSubDir' } }。您可以docker build ...使用该additionalBuildArgs选项将其他参数传递给命令，如agent { dockerfile { additionalBuildArgs '--build-arg foo=bar' } }。

常用选项

这些是可以应用两个或多个agent实现的几个选项。除非明确说明，否则不需要。

标签: 一个字符串。运行Pipeline或个人的标签stage。
此选项对于node，docker和dockerfile，并且是必需的 node。
customWorkspace: 一个字符串。运行Pipeline或个人stage这agent 是这个自定义的工作空间内的应用，而不是默认的。它可以是相对路径，在这种情况下，自定义工作区将位于节点上的工作空间根目录下，也可以是绝对路径。例如：

agent {
    node {
        label 'my-defined-label'
        customWorkspace '/some/other/path'
    }
}

此选项是有效的node，docker和dockerfile。
reuseNode: 一个布尔值，默认为false。如果为true，则在同一工作空间中，而不是完全在新节点上运行Pipeline顶层指定的节点上的容器。
此选项适用于docker和dockerfile，并且仅在agent个人使用时才有效果stage。

例如：

Jenkinsfile (Declarative Pipeline)
pipeline {
    agent { docker 'maven:3-alpine' } 
    stages {
        stage('Example Build') {
            steps {
                sh 'mvn -B clean verify'
            }
        }
    }
}

：在给定名称和tag（maven:3-alpine）的新创建的容器中执行此Pipeline中定义的所有步骤。

Stage-level 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在Pipeline顶层定义确保执行者不会被不必要地分配。使用agent none也强制每个stage部分包含自己的agent部分

：使用此图像在新创建的容器中执行此阶段中的步骤

：在新创建的容器中使用前一个阶段的不同图像执行此阶段中的步骤

post

该post部分定义将在Pipeline运行或阶段结束时运行的操作。一些条件后的块的内支持post：部分 always，changed，failure，success，unstable，和aborted。这些块允许在Pipeline运行或阶段结束时执行步骤，具体取决于Pipeline的状态。

需要	没有
参数	没有
允许	在顶级`pipeline`块和每个`stage`块中。

条件

always: 运行，无论Pipeline运行的完成状态如何。
changed: 只有当前Pipeline运行的状态与先前完成的Pipeline的状态不同时，才能运行。
failure: 仅当当前Pipeline处于“失败”状态时才运行，通常在Web UI中用红色指示表示。
success: 仅当当前Pipeline具有“成功”状态时才运行，通常在具有蓝色或绿色指示的Web UI中表示。
unstable: 只有当前Pipeline具有“不稳定”状态，通常由测试失败，代码违例等引起，才能运行。通常在具有黄色指示的Web UI中表示。
aborted: 只有当前Pipeline处于“中止”状态时，才会运行，通常是由于Pipeline被手动中止。通常在具有灰色指示的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部分应放在Pipeline末端

：后条件块包含的步骤相同的步骤部分

steps

包含一个或多个阶段指令的序列，该stages部分是Pipeline描述的大部分“工作”的位置。建议stages至少包含至少一个阶段指令，用于连续交付过程的每个离散部分，如构建，测试和部署。

需要	是
参数	没有
允许	只有一次，在`pipeline`块内。

例如

Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    stages {
        stage('Example') {
            steps { 
                echo 'Hello World'
            }
        }
    }
}

：的stages部分将典型地遵循指令，例如agent， options等

脚步

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

需要	是
参数	没有
允许	在每个`stage`块内。

例如

Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    stages {
        stage('Example') {
            steps { 
                echo 'Hello World'
            }
        }
    }
}

：该steps部分必须包含一个或多个步骤

指令

环境

该environment指令指定一系列键值对，这些对值将被定义为所有步骤的环境变量或阶段特定步骤，具体取决于environment指令位于Pipeline中的位置。

该指令支持一种特殊的帮助方法credentials()，可以通过其在Jenkins环境中的标识符来访问预定义的凭据。对于类型为“Secret Text”的凭据，该 credentials()方法将确保指定的环境变量包含Secret Text内容。对于“标准用户名和密码”类型的凭证，指定的环境变量将被设置为， username:password并且将自动定义两个附加的环境变量：MYVARNAME_USR和MYVARNAME_PSW相应的。

需要	没有
参数	没有
允许	在`pipeline`块内或`stage`指令内。

例如：

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顶级pipeline块中使用的指令将适用于Pipeline中的所有步骤

：在一个environment意图中定义的一个指令stage将仅将给定的环境变量应用于该过程中的步骤stage

：该environment块具有一个帮助方法credentials()，可用于在Jenkins环境中通过其标识符访问预定义的凭据

选项

该options指令允许在Pipeline本身内配置Pipeline专用选项。Pipeline提供了许多这些选项，例如buildDiscarder，但它们也可能由插件提供，例如 timestamps。

需要	没有
参数	没有
允许	只有一次，在`pipeline`块内。

可用选项

buildDiscarder: 持久化工件和控制台输出，用于最近Pipeline运行的具体数量。例如：options { buildDiscarder(logRotator(numToKeepStr: '1')) }
disableConcurrentBuilds: 不允许并行执行Pipeline。可用于防止同时访问共享资源等。例如：options { disableConcurrentBuilds() }
skipDefaultCheckout: 在agent指令中默认跳过来自源代码控制的代码。例如：options { skipDefaultCheckout() }
skipStagesAfterUnstable: 一旦构建状态进入了“不稳定”状态，就跳过阶段。例如：options { skipStagesAfterUnstable() }
timeout: 设置Pipeline运行的超时时间，之后Jenkins应该中止Pipeline。例如：options { timeout(time: 1, unit: 'HOURS') }
retry: 失败后，重试整个Pipeline指定的次数。例如：options { retry(3) }
timestamps: 预处理由Pipeline生成的所有控制台输出运行时间与发射线的时间。例如：options { timestamps() }

例如：

Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    options {
        timeout(time: 1, unit: 'HOURS') 
    }
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

：指定一个小时的全局执行超时，之后Jenkins将中止Pipeline运行。

完整的INFRA-1503完整列表可供选择

参数

该parameters指令提供用户在触发Pipeline时应提供的参数列表。这些用户指定的参数的值通过该params对象可用于Pipeline步骤，具体用法见示例。

需要	没有
参数	没有
允许	只有一次，在`pipeline`块内。

可用参数

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}"
            }
        }
    }
}

INFRA-1503的完整列表可供参考 。

触发器

该triggers指令定义了Pipeline应重新触发的自动化方式。对于与源代码集成的Pipeline，如GitHub或BitBucket，triggers可能不需要基于webhook的集成可能已经存在。目前只有两个可用的触发器是cron和pollSCM。

需要	没有
参数	没有
允许	只有一次，在`pipeline`块内。

cron: 接受一个cron风格的字符串来定义Pipeline应重新触发的常规间隔，例如： triggers { cron('H 4/* 0 0 1-5') }
pollSCM: 接受一个cron风格的字符串来定义Jenkins应该检查新的源更改的常规间隔。如果存在新的更改，则Pipeline将被重新触发。例如：triggers { pollSCM('H 4/* 0 0 1-5') }

该pollSCM触发器仅在Jenkins 2.22或更高版本可用

例如：

Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    triggers {
        cron('H 4/* 0 0 1-5')
    }
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

stage

该stage指令在该stages部分中，应包含步骤部分，可选agent部分或其他特定于阶段的指令。实际上，Pipeline完成的所有实际工作都将包含在一个或多个stage指令中。

需要	最后一个
参数	一个强制参数，一个用于舞台名称的字符串。
允许	在`stages`部分内。

例如：

Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

工具

定义自动安装和放置工具的部分PATH。如果agent none指定，这将被忽略。

需要	没有
参数	没有
允许	在`pipeline`块或`stage`块内。

支持的工具

maven jdk gradle 例如：

Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    tools {
        maven 'apache-maven-3.0.1' 
    }
    stages {
        stage('Example') {
            steps {
                sh 'mvn --version'
            }
        }
    }
}

：工具名称必须在Jenkins 管理Jenkins → 全局工具配置中预配置。

when

该when指令允许Pipeline根据给定的条件确定是否执行该阶段。该when指令必须至少包含一个条件。如果when指令包含多个条件，则所有子条件必须为舞台执行返回true。这与子条件嵌套在一个allOf条件中相同（见下面的例子）。

更复杂的条件结构可使用嵌套条件建：not，allOf或anyOf。嵌套条件可以嵌套到任意深度。

需要	没有
参数	没有
允许	在`stage`指令内

内置条件

branch: 当正在构建的分支与给出的分支模式匹配时执行stage，例如：when { branch 'master' }。请注意，这仅适用于多分支Pipeline。
environment: 当指定的环境变量设置为给定值时执行stage，例如： when { environment name: 'DEPLOY_TO', value: 'production' }
expression: 当指定的Groovy表达式求值为true时执行stage，例如： when { expression { return params.DEBUG_BUILD } }
not: 当嵌套条件为false时执行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' } }

例如：

Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    stages {
        stage('Example Build') {
            steps {
                echo 'Hello World'
            }
        }
        stage('Example Deploy') {
            when {
                branch 'production'
            }
            steps {
                echo 'Deploying'
            }
        }
    }
}

Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    stages {
        stage('Example Build') {
            steps {
                echo 'Hello World'
            }
        }
        stage('Example Deploy') {
            when {
                branch 'production'
                environment name: 'DEPLOY_TO', value: 'production'
            }
            steps {
                echo 'Deploying'
            }
        }
    }
}

Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    stages {
        stage('Example Build') {
            steps {
                echo 'Hello World'
            }
        }
        stage('Example Deploy') {
            when {
                allOf {
                    branch 'production'
                    environment name: 'DEPLOY_TO', value: 'production'
                }
            }
            steps {
                echo 'Deploying'
            }
        }
    }
}

Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    stages {
        stage('Example Build') {
            steps {
                echo 'Hello World'
            }
        }
        stage('Example Deploy') {
            when {
                branch 'production'
                anyOf {
                    environment name: 'DEPLOY_TO', value: 'production'
                    environment name: 'DEPLOY_TO', value: 'staging'
                }
            }
            steps {
                echo 'Deploying'
            }
        }
    }
}

Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    stages {
        stage('Example Build') {
            steps {
                echo 'Hello World'
            }
        }
        stage('Example Deploy') {
            when {
                expression { BRANCH_NAME ==~ /(production|staging)/ }
                anyOf {
                    environment name: 'DEPLOY_TO', value: 'production'
                    environment name: 'DEPLOY_TO', value: 'staging'
                }
            }
            steps {
                echo 'Deploying'
            }
        }
    }
}

Steps

声明性Pipeline可以使用“ Pipeline步骤”引用中记录的所有可用步骤，其中包含一个完整的步骤列表，并附加以下列出的步骤，仅在声明性PipelinePipeline Pipeline 中支持。

script

该script步骤需要一个script Pipeline，并在声明性Pipeline中执行。对于大多数用例，script声明Pipeline中的步骤不是必须的，但它可以提供一个有用的“escape hatch”。script不平凡的大小和/或复杂性的块应该转移到共享库中。

例如：

Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'

                script {
                    def browsers = ['chrome', 'firefox']
                    for (int i = 0; i < browsers.size(); ++i) {
                        echo "Testing the ${browsers[i]} browser"
                    }
                }
            }
        }
    }
}

Scripted Pipeline

Scripted Pipeline，如声明式Pipeline，构建在底层Pipeline子系统之上。不像声明，Scripted Pipeline有效地是一个通用的DSL构建与Groovy。由Groovy语言提供的大多数功能都提供给Scripted Pipeline的用户，这意味着它可以是一个非常富有表现力和灵活性的工具，可以通过这些工具来创建连续的传送Pipeline。

Flow Control

Scripted Pipeline从顶部顺序执行，与Jenkinsfile Groovy或其他语言中的大多数传统Scripted一样。因此，提供流量控制取决于Groovy表达式，例如 if/else条件，例如：

Jenkinsfile (Scripted Pipeline)
node {
    stage('Example') {
        if (env.BRANCH_NAME == 'master') {
            echo 'I only execute on the master branch'
        } else {
            echo 'I execute elsewhere'
        }
    }
}

可以管理Scripted Pipeline流控制的另一种方式是使用Groovy的异常处理支持。当步骤由于任何原因而导致异常时。处理错误行为必须使用try/catch/finallyGroovy 中的块，例如：

Jenkinsfile (Scripted Pipeline)
node {
    stage('Example') {
        try {
            sh 'exit 1'
        }
        catch (exc) {
            echo 'Something failed, I should sound the klaxons!'
            throw
        }
    }
}

Steps

如“ 入门指南 ”所述，Pipeline最基本的部分是“步骤”。从根本上说，步骤告诉Jenkins 要做什么，并且作为Declarative和Scripted Pipeline语法的基本构建块。

Scripted Pipeline并没有介绍这是专门针对它的语法的任何步骤; Pipeline步骤参考，其中包含Pipeline和插件提供的完整步骤列表。

与简单的Groovy的区别

为了提供耐久性，这意味着运行Pipeline可以在重新启动Jenkins主站后保留，Scripted Pipeline必须将数据序列化回主站。由于这个设计要求，一些Groovy成语如collection.each { item -> /* perform operation */ }没有完全支持。有关更多信息，请参见 JENKINS-27421和 JENKINS-26481。

语法比较

当Jenkins Pipeline首次创建时，Groovy被选为基础。Jenkins长期运用嵌入式Groovy引擎，为管理员和用户提供高级脚本功能。此外，Jenkins Pipeline的实施者发现Groovy是建立现在称为“Scripted Pipeline”DSL的坚实基础。

由于它是一个功能齐全的编程环境，Scripted Pipeline为Jenkins用户提供了极大的灵活性和可扩展性。Groovy学习曲线通常不适用于给定团队的所有成员，因此，创建声明性Pipeline是为了创作Jenkins Pipeline提供一个更简单和更有见解的语法。

两者基本上是下面相同的Pipeline 子系统。它们都是“Pipeline代码”的持久实现。他们都能够使用Pipeline内置的插件或插件提供的步骤。两者都可以利用共享库

不同之处在于语法和灵活性。声明性限制了用户具有更严格和预定义结构的可用性，使其成为更简单连续输送Pipeline的理想选择。脚本化提供了极少的限制，因为Groovy本身只能对结构和语法进行限制，而不是任何Pipeline专用系统，使其成为电力用户和具有更复杂要求的用户的理想选择。顾名思义，Declarative Pipeline鼓励声明式编程模型。尽管Scripted Pipeline遵循更命令性的编程模型。

← Pipeline 开发工具

BlueOcean介绍 →

Pipeline 语法

声明Pipeline

Sections

agent

参数

常用选项

例如：

post

条件

例如：

steps

例如

脚步

例如

指令

环境

例如：

选项

可用选项

例如：

参数

可用参数

例如：

触发器

stage

例如：

工具

支持的工具

例如：

when

内置条件

例如：

Steps

script

例如：

Scripted Pipeline

Flow Control

Steps

与简单的Groovy的区别

语法比较

推荐文章

推荐教程

最新教程