Jenkins pipeline：pipeline 使用之語法詳解

YatHo發表於2017-11-18
Jenkins

一、引言

　　Jenkins 2.0的到來，pipline進入了視野，jenkins2.0的核心特性. 也是最適合持續交付的feature。

　　簡單的來說，就是把Jenkins1.0版本中，Project中的相關配置資訊，如SVN/Git的配置，Parameter的配置等都變成Code，即Pipeline as Code。

　　隨著pipeline交付流水線在團隊中的推廣，使用pipeline指令碼的job也迅速增加。

　　　　優勢：

    • 　　　　通過寫程式碼的形式配置Project，且Jenkins中內建了常用的steps。
    • 　　　　實現了構建步驟程式碼化、構建過程檢視化。

二、語法簡介

　　Pipeline最基本的部分是“step”。基本上，step告訴Jenkins 要做什麼，並且作為Declarative Pipeline和Scripted Pipeline語法的基本構建塊。 
　　Pipeline支援兩種語法：Declarative Pipeline（在Pipeline 2.5中引入，結構化方式）和Scripted Pipeline，兩者都支援建立連續輸送的Pipeline。

選擇Declarative Pipeline還是Scripted Pipeline

　　最開始的Pipeline plugin，支援的只有一種指令碼型別，就是Scripted Pipeline；
　　Declarative Pipeline為Pipeline plugin在2.5版本之後新增的一種指令碼型別，與原先的Scripted Pipeline一樣，都可以用來編寫指令碼。

　　相關資料：

　　https://stackoverflow.com/questions/43484979/jenkins-scripted-pipeline-or-declarative-pipeline
　　http://jenkins-ci.361315.n4.nabble.com/Declarative-pipelines-vs-scripted-td4891792.html

　　從檢索的資料來看，Declarative Pipeline 是後續Open Blue Ocean所支援的型別。相對而言，Declarative Pipeline比較簡單，Declarative Pipeline中，也是可以內嵌Scripted Pipeline程式碼的。

　　為與BlueOcean指令碼編輯器相容，通常建議使用Declarative Pipeline的方式進行編寫,從jenkins社群的動向來看，很明顯這種語法結構也會是未來的趨勢。

三、Declarative Pipeline

Declarative Pipeline是Jenkins Pipeline 的一個相對較新的補充， 它在Pipeline子系統之上提出了一種更為簡化和有意義的語法。
所有有效的Declarative Pipeline必須包含在一個pipeline塊內，例如：
pipeline { /* insert Declarative Pipeline here */ }
Declarative Pipeline中的基本語句和表示式遵循與Groovy語法相同的規則 ，但有以下例外：

  • 　　a.Pipeline的頂層必須是塊，具體來說是：pipeline { }
  • 　　b.沒有分號作為語句分隔符。每個宣告必須在自己的一行
  • 　　c.塊只能包含Sections, Directives, Steps或賦值語句。
  • 　　d.屬性引用語句被視為無參方法呼叫。所以例如，輸入被視為input（）

1.Sections（章節）

　　Declarative Pipeline裡的Sections通常包含一個或多個Directives或 Steps

agent

　　agent部分指定整個Pipeline或特定階段將在Jenkins環境中執行的位置，具體取決於該agent 部分的放置位置。該部分必須在pipeline塊內的頂層定義 ，但stage級使用是可選的。

　　
　　為了支援Pipeline可能擁有的各種用例，該agent部分支援幾種不同型別的引數。這些引數可以應用於pipeline塊的頂層，也可以應用在每個stage指令內。
引數
　　any

　　　　在任何可用的agent 上執行Pipeline或stage。例如：agent any
　　none
　　　　當在pipeline塊的頂層使用none時，將不會為整個Pipeline執行分配全域性agent ，每個stage部分將需要包含其自己的agent部分。
　　label
　　　　使用提供的label標籤，在Jenkins環境中可用的代理上執行Pipeline或stage。例如：agent { label 'my-defined-label' }
　　node
　　　　agent { node { label 'labelName' } }，等同於 agent { label 'labelName' }，但node允許其他選項（如customWorkspace）。
　　docker
　　　　定義此引數時，執行Pipeline或stage時會動態供應一個docker節點去接受Docker-based的Pipelines。 docker還可以接受一個args，直接傳遞給docker run呼叫。例如：agent { docker 'maven:3-alpine' }或

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

　　dockerfile

　　　　使用從Dockerfile源儲存庫中包含的容器來構建執行Pipeline或stage 。為了使用此選項，Jenkinsfile必須從Multibranch Pipeline或“Pipeline from SCM"載入。
　　　　預設是在Dockerfile源庫的根目錄：agent { dockerfile true }。如果Dockerfile需在另一個目錄中建立，請使用以下dir選項：agent { dockerfile { dir 'someSubDir' } }。您可以通過docker build ...使用additionalBuildArgs選項，如agent { 　　　　dockerfile { additionalBuildArgs '--build-arg foo=bar' } }。

 

引數
any
　　在任何可用的agent 上執行Pipeline或stage。例如：agent any
none
　　當在pipeline塊的頂層使用none時，將不會為整個Pipeline執行分配全域性agent ，每個stage部分將需要包含其自己的agent部分。
label
　　使用提供的label標籤，在Jenkins環境中可用的代理上執行Pipeline或stage。例如：agent { label 'my-defined-label' }
node
　　agent { node { label 'labelName' } }，等同於 agent { label 'labelName' }，但node允許其他選項（如customWorkspace）。
docker
　　定義此引數時，執行Pipeline或stage時會動態供應一個docker節點去接受Docker-based的Pipelines。 docker還可以接受一個args，直接傳遞給docker run呼叫。例如：agent { docker 'maven:3-alpine' }或

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

dockerfile
使用從Dockerfile源儲存庫中包含的容器來構建執行Pipeline或stage 。為了使用此選項，Jenkinsfile必須從Multibranch Pipeline或“Pipeline from SCM"載入。
預設是在Dockerfile源庫的根目錄：agent { dockerfile true }。如果Dockerfile需在另一個目錄中建立，請使用以下dir選項：agent { dockerfile { dir 'someSubDir' } }。您可以通過docker build ...使用additionalBuildArgs選項，如agent { dockerfile { additionalBuildArgs '--build-arg foo=bar' } }。

常用選項

這些是可以應用於兩個或多個agent的選項。除非明確定義，否則不需要。
　　label
　　　　一個字串。標記在哪裡執行pipeline或stage
　　　　此選項適用於node，docker和dockerfile，並且 node是必需的。
　　customWorkspace
　　　　一個字串。自定義執行的工作空間內。它可以是相對路徑，在這種情況下，自定義工作區將位於節點上的工作空間根目錄下，也可以是絕對路徑。例如：

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

　　reuseNode
　　　　一個布林值，預設為false。如果為true，則在同一工作空間中。
　　　　此選項適用於docker和dockerfile，並且僅在 individual stage中使用agent才有效。

pipeline {
    //Execute all the steps defined in this Pipeline within a newly created container of the given name and tag (maven:3-alpine).
    agent { docker 'maven:3-alpine' } 
    stages {
        stage('Example Build') {
            steps {
                sh 'mvn -B clean verify'
            }
        }
    }
}

　　

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

　　

post

　　定義Pipeline或stage執行結束時的操作。post-condition塊支援post部件：always，changed，failure，success，unstable，和aborted。這些塊允許在Pipeline或stage執行結束時執行步驟，具體取決於Pipeline的狀態。

　　

　　conditions項：
　　always
　　　　執行，無論Pipeline執行的完成狀態如何。
　　changed
　　　　只有當前Pipeline執行的狀態與先前完成的Pipeline的狀態不同時，才能執行。
　　failure
　　　　僅噹噹前Pipeline處於“失敗”狀態時才執行，通常在Web UI中用紅色指示表示。
　　success
　　　　僅噹噹前Pipeline具有“成功”狀態時才執行，通常在具有藍色或綠色指示的Web UI中表示。
　　unstable
　　　　只有當前Pipeline具有“不穩定”狀態，通常由測試失敗，程式碼違例等引起，才能執行。通常在具有黃色指示的Web UI中表示。
　　aborted
　　　　只有當前Pipeline處於“中止”狀態時，才會執行，通常是由於Pipeline被手動中止。通常在具有灰色指示的Web UI中表示。

pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
    post { 
        always { 
            echo 'I will always say Hello again!'
        }
    }
}

stages

　　包含一個或多個stage的序列，Pipeline的大部分工作在此執行。建議stages至少包含至少一個stage指令，用於連線各個交付過程，如構建，測試和部署等。
　　

steps

　　steps包含一個或多個在stage塊中執行的step序列。
　　

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

　　

2.Directives （指令）

　　environment

environment指令指定一系列鍵值對，這些鍵值對將被定義為所有step或stage-specific step的環境變數，具體取決於environment指令在Pipeline中的位置。
該指令支援一種特殊的方法credentials()，可以通過其在Jenkins環境中的識別符號來訪問預定義的憑據。
對於型別為“Secret Text”的憑據，該 credentials()方法將確保指定的環境變數包含Secret Text內容；對於“標準使用者名稱和密碼”型別的憑證，指定的環境變數將被設定為username:password。
　　

pipeline {
    agent any
    environment { 
        CC = 'clang'
    }
    stages {
        stage('Example') {
            environment { 
                AN_ACCESS_KEY = credentials('my-prefined-secret-text') 
            }
            steps {
                sh 'printenv'
            }
        }
    }
}

　　

options

options指令允許在Pipeline本身內配置Pipeline專用選項。Pipeline本身提供了許多選項，例如buildDiscarder，但它們也可能由外掛提供，例如 timestamps。

　　
可用選項

　　buildDiscarder
　　　　pipeline保持構建的最大個數。例如：options { buildDiscarder(logRotator(numToKeepStr: '1')) }
　　disableConcurrentBuilds
　　　　不允許並行執行Pipeline,可用於防止同時訪問共享資源等。例如：options { disableConcurrentBuilds() }
　　skipDefaultCheckout
　　　　預設跳過來自原始碼控制的程式碼。例如：options { skipDefaultCheckout() }
　　skipStagesAfterUnstable
　　　　一旦構建狀態進入了“Unstable”狀態，就跳過此stage。例如：options { skipStagesAfterUnstable() }
　　timeout
　　　　設定Pipeline執行的超時時間。例如：options { timeout(time: 1, unit: 'HOURS') }
　　retry
　　　　失敗後，重試整個Pipeline的次數。例如：options { retry(3) }
　　timestamps
　　　　預定義由Pipeline生成的所有控制檯輸出時間。例如：options { timestamps() }

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

parameters

parameters指令提供使用者在觸發Pipeline時的引數列表。這些引數值通過該params物件可用於Pipeline步驟，具體用法如下

　　

可用引數
　　string
　　　　A parameter of a string type, for example: parameters { string(name: 'DEPLOY_ENV', defaultValue: 'staging', description: '') }
　　booleanParam
　　　　A boolean parameter, for example: parameters { booleanParam(name: 'DEBUG_BUILD', defaultValue: true, description: '') }
　　目前只支援[booleanParam, choice, credentials, file, text, password, run, string]這幾種引數型別，其他高階引數化型別還需等待社群支援。

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

triggers

triggers指令定義了Pipeline自動化觸發的方式。對於與原始碼整合的Pipeline，如GitHub或BitBucket，triggers可能不需要基於webhook的整合也已經存在。目前只有兩個可用的觸發器：cron和pollSCM。

　　
cron
　　接受一個cron風格的字串來定義Pipeline觸發的常規間隔，例如： triggers { cron('H 4/* 0 0 1-5') }
pollSCM
　　接受一個cron風格的字串來定義Jenkins檢查SCM源更改的常規間隔。如果存在新的更改，則Pipeline將被重新觸發。例如：triggers { pollSCM('H 4/* 0 0 1-5') }
pipeline {
    agent any
    triggers {
        cron('H 4/* 0 0 1-5')
    }
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

stage

 stage指令在stages部分中，應包含stop部分，可選agent部分或其他特定於stage的指令。實際上，Pipeline完成的所有實際工作都將包含在一個或多個stage指令中。

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

tools

 通過tools可自動安裝工具，並放置環境變數到PATH。如果agent none，這將被忽略。

　　
Supported Tools(Global Tool Configuration)
　　maven
　　jdk
　　gradle

 

pipeline {
    agent any
    tools {
        //工具名稱必須在Jenkins 管理Jenkins → 全域性工具配置中預配置。
        maven 'apache-maven-3.0.1'
    }
    stages {
        stage('Example') {
            steps {
                sh 'mvn --version'
            }
        }
    }
}

　　

when

　　when指令允許Pipeline根據給定的條件確定是否執行該階段。該when指令必須至少包含一個條件。如果when指令包含多個條件，則所有子條件必須為stage執行返回true。這與子條件巢狀在一個allOf條件中相同（見下面的例子）。
更復雜的條件結構可使用巢狀條件建：not，allOf或anyOf。巢狀條件可以巢狀到任意深度。

　　
　　內建條件
　　branch
　　　　當正在構建的分支與給出的分支模式匹配時執行，例如：when { branch 'master' }。請注意，這僅適用於多分支Pipeline。
　　environment
　　　　當指定的環境變數設定為給定值時執行，例如： when { environment name: 'DEPLOY_TO', value: 'production' }
　　expression
　　　　當指定的Groovy表示式求值為true時執行，例如： when { expression { return params.DEBUG_BUILD } }
　　not
　　　　當巢狀條件為false時執行。必須包含一個條件。例如：when { not { branch 'master' } }
　　allOf
　　　　當所有巢狀條件都為真時執行。必須至少包含一個條件。例如：when { allOf { branch 'master'; environment name: 'DEPLOY_TO', value: 'production' } }
　　anyOf
　　　　當至少一個巢狀條件為真時執行。必須至少包含一個條件。例如：when { anyOf { branch 'master'; branch 'staging' } }

 

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

　　

3.Parallel(並行)

Declarative Pipeline近期新增了對並行巢狀stage的支援，對耗時長，相互不存在依賴的stage可以使用此方式提升執行效率。除了parallel stage，單個parallel裡的多個step也可以使用並行的方式執行。

pipeline {
    agent any
    stages {
        stage('Non-Parallel Stage') {
            steps {
                echo 'This stage will be executed first.'
            }
        }
        stage('Parallel Stage') {
            when {
                branch 'master'
            }
            parallel {
                stage('Branch A') {
                    agent {
                        label "for-branch-a"
                    }
                    steps {
                        echo "On Branch A"
                    }
                }
                stage('Branch B') {
                    agent {
                        label "for-branch-b"
                    }
                    steps {
                        echo "On Branch B"
                    }
                }
            }
        }
    }
}

　　

4.Steps（步驟）

Declarative Pipeline可以使用 Pipeline Steps reference中的所有可用步驟 ，並附加以下僅在Declarative Pipeline中支援的步驟。

script

script步驟需要一個script Pipeline，並在Declarative Pipeline中執行。對於大多數用例，script在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

　　Groovy指令碼不一定適合所有使用者，因此jenkins建立了Declarative pipeline，為編寫Jenkins管道提供了一種更簡單、更有主見的語法。但是不可否認，由於指令碼化的pipeline是基於groovy的一種DSL語言，所以與Declarative pipeline相比為jenkins使用者提供了更巨大的靈活性和可擴充套件性。

1.流程控制

　　pipeline指令碼同其它指令碼語言一樣，從上至下順序執行，它的流程控制取決於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'
        }
    }
}

　　pipeline指令碼流程控制的另一種方式是Groovy的異常處理機制。當任何一個步驟因各種原因而出現異常時，都必須在Groovy中使用try/catch/finally語句塊進行處理，舉例如下：

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

　　

2.Steps

　　pipeline最核心和基本的部分就是“step”，從根本上來說，steps作為Declarative pipeline和Scripted pipeline語法的最基本的語句構建塊來告訴jenkins應該執行什麼操作。
Scripted pipeline沒有專門將steps作為它的語法的一部分來介紹，但是在Pipeline Steps reference這篇文件中對pipeline及其外掛涉及的steps做了很詳細的介紹。如有需要可參考jenkins官網對該部分的介紹Pipeline Steps reference

3.Differences from plain Groovy

　　由於pipeline的一些個性化需求，比如在重新啟動jenkins後要求pipeline指令碼仍然可以執行，那麼pipeline指令碼必須將相關資料做序列化，然而這一點 Groovy並不能完美的支援，例如collection.each { item -> /* perform operation */ }

4.Declarative pipeline和Scripted pipeline的比較

共同點：
　　兩者都是pipeline程式碼的持久實現，都能夠使用pipeline內建的外掛或者外掛提供的steps，兩者都可以利用共享庫擴充套件。
區別：
　　兩者不同之處在於語法和靈活性。Declarative pipeline對使用者來說，語法更嚴格，有固定的組織結構，更容易生成程式碼段，使其成為使用者更理想的選擇。但是Scripted pipeline更加靈活，因為Groovy本身只能對結構和語法進行限制，對於更復雜的pipeline來說，使用者可以根據自己的業務進行靈活的實現和擴充套件。

相關文章