Loading

【Jenkins系列】-Pipeline語法全集

Jenkins為您提供了兩種開發Pipeline的方式：腳本式和聲明式。

腳本式流水線（也稱為“傳統”流水線）基于Groovy作為其特定于域的語言。
而聲明式流水線提供了簡化且更友好的語法，并帶有用于定義它們的特定語句，而無需學習Groovy。聲明式流水線語法錯誤在腳本開始時報告。這是一個很好的功能，因為您不會浪費時間，直到某個步驟未能意識到拼寫錯誤或拼寫錯誤。如前所述，流水線可以以聲明式或腳本式編寫。而且，聲明式方法建立在腳本式方法的基礎之上，通過添加”script”步驟，可以很容易地進行擴展。

聲明式流水線 vs 腳本式流水線
共同點：

兩者都是pipeline代碼的持久實現，都能夠使用pipeline內置的插件或者插件提供的steps，兩者都可以利用共享庫擴展。

區別：

兩者不同之處在于語法和靈活性。
Declarative pipeline對用戶來說，語法更嚴格，有固定的組織結構，更容易生成代碼段，使其成為用戶更理想的選擇。
但是Scripted pipeline更加靈活，因為Groovy本身只能對結構和語法進行限制，對于更復雜的pipeline來說，用戶可以根據自己的業務進行靈活的實現和擴展

聲明式流水線

必須使用pipeline語句定義有效的聲明式流水線，并包括以下必需的部分：

agent
stages
stage
steps

另外，還有這些可用的指令：

environment (在流水線或階段級別定義)
input (階段級別定義)
options (在流水線或階段級別定義)
parallel
parameters
post
dcript
tools
triggers
when

現在，我們將從所需的指令/部分開始，對列出的每個指令/部分進行描述。

agent

agent	agent部分指定整個Pipeline或特定階段將在Jenkins環境中執行的位置，具體取決于該agent 部分的放置位置
需要	必須存在，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 - dockerfile:使用從Dockerfile源存儲庫中包含的容器來構建執行Pipeline或stage 。
常用參數	這些是可以應用于兩個或多個agent的選項。除非明確定義，否則不需要。 label：一個字符串。標記在哪里運行pipeline或stage。此選項適用于node，docker和dockerfile，并且 node是必需的。 customWorkspace：一個字符串。自定義運行的工作空間內。它可以是相對路徑，在這種情況下，自定義工作區將位于節點上的工作空間根目錄下，也可以是絕對路徑。例如： reuseNode：一個布爾值，默認為false。如果為true，則在同一工作空間中。此選項適用于docker和dockerfile，并且僅在 individual stage中使用agent才有效。

agent { label 'this k8s-api-label'} 
agent {
    node{
        label ' this is k8sapi-label'
        customWorkspace '/some/other/path'
    }
}
agent {
    docker {
        image 'im-web'
        label 'this is k8sapi-label'
        args '-v /tmp:/tmp'
    }
}

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

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

options

options	options指令允許在Pipeline本身內配置Pipeline專用選項
需要	否，預定義pipeline專有的配置信息，僅可定義一次
參數	無
說明	在流水線級別定義，此指令將對整個流水線的特定選項進行分組?？捎玫倪x項有： - 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 {
        retry(3)  //將流水線配置為在失敗前重試3次：
    }
    stages {
        echo 'do something'
    }
}

parameters

parameters指令提供用戶在觸發Pipeline時的參數列表。這些參數值通過該params對象可用于Pipeline步驟
目前只支持[booleanParam, choice, credentials, file, text, password, run, string]這幾種參數類型，其他高級參數化類型還需等待社區支持。

parameters
需要	否，定義參數化構建的參數
參數	無
說明	Only once, inside the pipeline block

pipeline {
    agent any
    parameters {
        string(name: 'user', defaultValue: 'John', description: 'A user that triggers the pipeline')
    }
    stages {
        stage('Trigger pipeline') {
            steps {
                echo "Pipeline triggered by ${params.USER}"
            }
        }
    }
}

pipeline {
    agent any

    options {
        timeout(time:1, unit: 'HOURS')
    }

    parameters {
        choice(name:'PerformMavenRelease',choices:'False\nTrue',description:'desc')
        //   password(name:'CredsToUse',defaultValue:'',description:'A password to build with')
    }

    environment {
        SONAR_SERVER = 'http://172.16.230.171:9000'
        JAVA_HOME='/data/jdk'
    }

    stages {
        stage('sonarserver') {
            steps {
                echo "${SONAR_SERVER}"
            }
        }
        stage('javahome') {
            steps {
                echo "${JAVA_HOME}"
            }
        }
        stage('get parameters') {
            steps {
                echo "${params.PerformMavenRelease}"
            }
        }        
    }
}

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

stages

stages	包含一個或多個stage的序列，Pipeline的大部分工作在此執行。建議stages至少包含至少一個stage指令，用于連接各個交付過程，如構建，測試和部署等
需要	是
參數	無
常用選項	構建后操作的內置判定條件 always, changed, failure, sucess,unstable,aborted

pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
    stage('echo') {
        steps {
            echo 'I will ........!'
        }
    }
}

steps

steps
需要	是，steps位于stage指令塊內部，包括一個或者多個step
參數	無
說明	僅有一個step的情況下可以忽略關鍵字step及其{}

pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
    sh 'echo "A one line step"'
    sh '''
    echo "A multiline step"'
    cd /tests/results
    ls -lrt
    '''
}
        }
    }
    stage('echo') {
        steps {  
    bat "mvn clean test -Dsuite=SMOKE_TEST -Denvironment=QA"
    powershell ".\funcional_tests.ps1"
}
    }
}

environment

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

environment
需要	是，environment 定義了一組全局的環境變量鍵值對
參數	無
說明	存在于pipeline{} 或者stage指令內，注意特殊方法credentials() ,可以獲取jenkins中預定義的憑證明文內容

//在“pipeline”級別：
pipeline {
    agent any
    
    environment {
        SONAR_SERVER = 'http://172.16.230.171:9000'
    }
    
    stages {
        stage('Example') {
            steps {
                echo "${SONAR_SERVER}"
            }
        }
    }
}

//在”stage”級別：

pipeline {
    agent any
    stages {
        stage ('build') {
            environment {
                OUTPUT_PATH = './outputs/'
            }
            ...
        }
        ...
    }
}

input

“input”指令在階段級別定義，提供提示輸入的功能。該階段將被暫停，直到用戶手動確認為止。
以下配置選項可用于此指令：

message：這是必需的選項，其中指定了要顯示給用戶的消息。
id：可選標識符。默認情況下，使用“階段”名稱。
ok：“確定”按鈕的可選文本。
submitter：允許提交輸入的用戶或外部組名的可選列表。默認情況下，允許任何用戶。
submitterParameter：要使用提交者名稱設置的環境變量的可選名稱（如果存在）。
parameters：提交者將提供的可選參數列表。

這是包含此指令的示例流水線：

pipeline {
    agent any
    stages {
        stage ('build') {
            input{
               message "Press Ok to continue"
               submitter "user1,user2"
                parameters {
                   string(name:'username', defaultValue: 'user', description: 'Username of the user pressing Ok')
                }
            }
            steps { 
                echo "User: ${username} said Ok."
            }
        }
    }
}

parallel

Jenkins流水線階段可以在內部嵌套其他階段，這些階段將并行執行。這是通過在腳本中添加“parallel”指令來完成的。使用示例：

stage('run-parallel-branches') {
    steps {
        parallel(
            a: {
                echo "Tests on Linux"
            },
            b: {
            echo "Tests on Windows"
            }
        )
    }
}

從聲明式流水線1.2版開始，引入了一種新語法，使并行語法的使用更像聲明式的。
使用此新語法重寫的先前腳本如下所示：

pipeline {
    agent none
    stages {
        stage('Run Tests') {
            parallel {
                stage('Test On Windows') {
                    agent {
                        label "windows"
                    }
                steps {
                    bat "run-tests.bat"
                }
                }
                stage('Test On Linux') {
                    agent {
                        label "linux"
                    }
                    steps {
                        sh "run-tests.sh"
                    }
                }
            }
        }
    }
}

上述的任何一個流水線都將如下所示：

由于兩個腳本都運行特定的平臺測試，因此它們將在不同的節點上運行測試。如果您的Jenkins服務器具有足夠的CPU，則還可以通過使用多線程將并行用于在同一節點上同時運行階段。
使用并行階段時有一些限制：

stage指令可以具有parallel指令或steps指令，但不能同時具有兩者。
parallel指令中的一個stage指令不能嵌套另一個parallel指令，僅允許steps。
在內部具有parallel指令的stage指令不能定義“agent”或“tools”指令。

post

post	定義Pipeline或stage運行結束時的操作。post-condition塊支持post部件：always，changed，failure，success，unstable，和aborted。這些塊允許在Pipeline或stage運行結束時執行步驟，具體取決于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中表示。

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

script

此步驟用于將腳本化流水線語句添加到聲明式流水線中，從而提供更多功能。此步驟必須包括在“stage”級別。
腳本塊可以多次用于不同的項目。這些塊使您可以擴展Jenkins功能，并可以實現為共享庫。可以在Jenkins共享庫中找到有關此內容的更多信息。同樣，可以將共享庫導入并使用到“script”中，從而擴展了流水線功能。
接下來，我們將提供示例流水線。第一個只有一個包含一段腳本化流水線代碼的塊，而第二個將展示如何導入和使用共享庫：

pipeline {
    agent any
    stages {
        stage('Sample') {
            steps {
                echo "Scripted block"
                script {

                }
            }
        }
    }
}

tools

可以在流水線級別或階段級別添加“tools”指令。它允許您指定要在腳本上使用的Maven，JDK或Gradle版本。必須在“全局工具配置”Jenkins菜單上配置這些工具中的任何一個，在撰寫本文時，這三個工具都受支持。
另外，Jenkins將嘗試安裝列出的工具（如果尚未安裝）。通過使用此指令，可以確保安裝了項目所需的特定版本。

pipeline {
    agent any
    tools {
        maven 'apache-maven-3.0.1'  ////工具名稱必須在Jenkins 管理Jenkins → 全局工具配置中預配置。
    }
    stages {
         echo 'do something'
    }
}

triggers

觸發器允許Jenkins通過使用以下任何一個可用的方式自動觸發流水線：

cron：通過使用cron語法，它可以定義何時重新觸發管道。
pollSCM：通過使用cron語法，它允許您定義Jenkins何時檢查新的源存儲庫更新。如果檢測到更改，則將重新觸發流水線。（從Jenkins 2.22開始可用）。
upstream：將Jenkins任務和閾值條件作為輸入。當列表中的任何任務符合閾值條件時，將觸發流水線。

帶有可用觸發器的示例流水線如下所示：

pipeline {
    agent any
    triggers {
        //Execute weekdays every four hours starting at minute 0
        cron('0 */4 * * 1-5')
    }
    stages {
        ...
    }
}



pipeline {
    agent any
    triggers {
        //Query repository weekdays every four hours starting at minute 0
        pollSCM('0 */4 * * 1-5')
    }
    stages {
        ...
    }
}

pipeline {
    agent any
    triggers {
        //Execute when either job1 or job2 are successful
        upstream(upstreamProjects: 'job1, job2', threshold: hudson.model.Result.SUCCESS)
    }
    stages {
        ...
    }
}

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

使用方法：
1.when 僅用于stage內部
2. when 的內置條件

when {branch 'master'} #當是master的時候，才執行某些事情
when {envionment name:'DEPLOY_TO',value:'production'} #當環境變量name 的值是production的時候，才執行某些事情
when {expression {return params.DEBUG_BUILD}} #表達式的返回值是真的情況下，才執行
when {not {branch 'master'}}#不是master的情況下，執行
when {allOf {branch 'master'; environment name: 'DEPLOY_TO',value:'production'}} #當大括號中所有的項都成立，才去做某些事情
when {anyOf {branch 'master'; branch 'staging'}} #只要滿足大括號里面的某一個條件，才去做某些事情

例如，流水線使您可以在具有多個分支的項目上執行任務。這被稱為多分支流水線，其中可以根據分支名稱（例如“master”，“ feature*”，“development”等）采取特定的操作。這是一個示例流水線，它將運行master分支的步驟：

pipeline {
    agent any
    stages {
        stage('Deploy stage') {
            when {
                branch 'master'
            }
            steps {
                echo 'Deploy master to stage'
            }
        }
    }
}

腳本式流水線

Groovy腳本不一定適合所有使用者，因此jenkins創建了Declarative pipeline，為編寫Jenkins管道提供了一種更簡單、更有主見的語法。
但是不可否認，由于腳本化的pipeline是基于groovy的一種DSL語言，所以與聲明式 pipeline相比為jenkins用戶提供了更巨大的靈活性和可擴展性。

流程控制if/else條件

pipeline腳本同其它腳本語言一樣，從上至下順序執行，它的流程控制取決于Groovy表達式，如if/else條件語句

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

異常處理try/catch/finally

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

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

循環

for循環僅存在域腳本式pipeline中，但是可以通過在聲明式pipeline中調用script step來執行

pipeline {
    agent any
    stages {
        stage('Example'){
            steps{
                echo 'Hello world!'
                script {
                    def browsers = ['chrome','firefox']
                    for (int i = 0;i < browers.size();++i){
                        echo "Testing the ${browsers[i]} browser"
                    }
                }
            }
        }
    }
}

于大多數用例，script在Declarative Pipeline中的步驟不是必須的，但它可以提供一個有用的加強。

參考

https://www.cyotek.com/blog/using-parameters-with-jenkins-pipeline-builds
https://digitalvarys.com/jenkins-declarative-pipeline-with-examples/

posted @ 2023-04-01 23:51 DevOps在路上閱讀(4372) 評論(0) 收藏舉報

刷新頁面返回頂部

Loading

DevOps在路上｜專注于團隊研發效能

熱愛devops文化，效能就是一切

【Jenkins系列】-Pipeline語法全集

聲明式流水線

agent

options

parameters

stages

steps

environment

input

parallel

post

script

tools

triggers

when

腳本式流水線

流程控制if/else條件

異常處理try/catch/finally

循環

參考

公告

Loading

DevOps在路上｜專注于團隊研發效能

熱愛devops文化，效能就是一切

【Jenkins系列】-Pipeline語法全集

聲明式流水線

agent

options

parameters

stages

steps

environment

input

parallel

post

script

tools

triggers

when

腳本式流水線

流程控制if/else條件

異常處理try/catch/finally

循環

參考

公告

熱愛devops文化，效能就是一切