《Jenkins 2.x實踐指南》讀書筆記-Jenkins 2.x pipeline語法

[TOC]

1. 大概了解Groovy

可以通過Groovy教程來了解。

2. pipeline介紹

Jenkins pipeline其實就是基于Groovy語言實現的一種DSL（領域特定語言），用于描述整條流水線是如何進行的。流水線的內容包括執行編譯、打包、測試、輸出測試報告等步驟。

2.1 pipeline最簡結構

pipeline {
    agent any 
    stages {
        stage('Stage 1') {
            steps {
                echo 'Hello world!' 
            }
        }
    }
}

• pipeline：代表整條流水線，包含整條流水線的邏輯。
• stage部分：階段，代表流水線的階段。每個階段都必須有名稱。本例中，build就是此階段的名稱。
• stages部分：流水線中多個stage的容器。stages部分至少包含一個stage。
• steps部分：代表階段中的一個或多個具體步驟（step）的容器。steps部分至少包含一個步驟，本例中，echo就是一個步驟。在一個stage中有且只有一個steps。
• agent部分：指定流水線的執行位置（Jenkins agent）。流水線中的每個階段都必須在某個地方（物理機、虛擬機或Docker容器）執行，agent部分即指定具體在哪里執行。

更多更詳細pipeline步驟參考文檔：
https://jenkins.io/zh/doc/pipeline/steps/

以上每一個部分（section）都是必需的，少一個，Jenkins都會報錯。

眾所周知，jenkins好用最大體現它的眾多插件滿足各種需求。并不是所有的插件都支持pipeline的。
jenkins插件兼容pipeline列表：
https://github.com/jenkinsci/pipeline-plugin/blob/master/COMPATIBILITY.md

2.2 post

post部分包含的是在整個pipeline或階段完成后一些附加的步驟。post部分是可選的，所以并不包含在pipeline最簡結構中。但這并不代表它作用不大。
根據pipeline或階段的完成狀態，post部分分成多種條件塊，包括：

• always：不論當前完成狀態是什么，都執行。
• changed：只要當前完成狀態與上一次完成狀態不同就執行。
• fixed：上一次完成狀態為失敗或不穩定（unstable），當前完成狀態為成功時執行。
• regression：上一次完成狀態為成功，當前完成狀態為失敗、不穩定或中止（aborted）時執行。
• aborted：當前執行結果是中止狀態時（一般為人為中止）執行。
• failure：當前完成狀態為失敗時執行。
• success：當前完成狀態為成功時執行。
• unstable：當前完成狀態為不穩定時執行。
• cleanup：清理條件塊。不論當前完成狀態是什么，在其他所有條件塊執行完成后都執行。post部分可以同時包含多種條件塊。以下是post部分的完整示例。

pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                sh 'echo Build stage ...'
            }
            post {
                always {
                    echo "post condition executed: always ..."
                }
                changed {
                    echo "post condition executed: changed ..."
                }
                aborted {
                    echo "post condition executed: aborted ..."
                }
                regression {
                    echo "post condition executed: regression ..."
                }
            }
        }

        stage('Test'){
            steps {
                sh 'echo Test stage ...'
            }
            post {
                aborted {
                    echo "post condition executed: aborted ..."
                }
                failure {
                    echo "post condition executed: failure ..."
                }
                success {
                    echo "post condition executed: success ..."
                }
            }
        }

        stage('Deploy') {
            steps {
                sh 'echo Deploy stage ...'
            }
        }
    }
        post {
        unstable {
            echo "post condition executed: unstable ..."
        }
        unsuccessful {
            echo "post condition executed: unsuccessful ..."
        }
        cleanup {
            echo "post condition executed: cleanup ..."
        }
    }
  }

2.3 pipeline支持的指令

顯然，基本結構滿足不了現實多變的需求。所以，Jenkins pipeline通過各種指令（directive）來豐富自己。指令可以被理解為對Jenkins pipeline基本結構的補充。
Jenkins pipeline支持的指令有：

• environment：用于設置環境變量，可定義在stage或pipeline部分。
• tools：可定義在pipeline或stage部分。它會自動下載并安裝我們指定的工具，并將其加入PATH變量中。
• input：定義在stage部分，會暫停pipeline，提示你輸入內容。
• options：用于配置Jenkins pipeline本身的選項，比如options {retry（3）}指當pipeline失敗時再重試2次。options指令可定義在stage或pipeline部分。
• parallel：并行執行多個step。在pipeline插件1.2版本后，parallel開始支持對多個階段進行并行執行。
• parameters：與input不同，parameters是執行pipeline前傳入的一些參數。
• triggers：用于定義執行pipeline的觸發器。
• when：當滿足when定義的條件時，階段才執行。

在使用指令時，需要注意的是每個指令都有自己的“作用域”。如果指令使用的位置不正確，Jenkins將會報錯。

2.4 配置pipeline本身

2.4.1 全局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
在失敗時, 重新嘗試整個流水線的指定次數。 例如: options { retry(3) }

timestamps
預謀所有由流水線生成的控制臺輸出，與該流水線發出的時間一致。 例如: options { timestamps() }

newContainerPerStage
當agent為docker或dockerfile時，指定在同一個Jenkins節點上，每個stage都分別運行在一個新的容器中，而不是所有stage都運行在同一個容器中。例如: options { newContainerPerStage() }

Example

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

指定一個小時的全局執行超時, 在此之后，Jenkins 將中止流水線運行。

2.4.2 階段option

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() }

Example

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

指定 Example 階段的執行超時時間, 在此之后，Jenkins 將中止流水線運行。

2.4.3 在聲明式pipeline中使用腳本

聲明式pipeline是不能直接在steps塊中寫Groovy代碼。
Jenkins pipeline專門提供了一個script步驟，你能在script步驟中像寫代碼一樣寫pipeline邏輯。

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                script {
                    result = sh (script: "git log -1|grep 'Release'", returnStatus: true) 
                    echo "result: ${result}"
                }
            }
        }
    }
}

在script塊中的其實就是Groovy代碼。大多數時候，我們是不需要使用script步驟的。如果在script步驟中寫了大量的邏輯，則說明你應該把這些邏輯拆分到不同的階段，或者放到共享庫中。共享庫是一種擴展Jenkins pipeline的技術。

2.5 pipeline內置基礎步驟

這里介紹pipeline內置的一些步驟。

2.5.1 文件目錄相關步驟

deleteDir
刪除當前目錄，它是一個無參步驟，刪除的是當前工作目錄。通常它與dir步驟一起使用，用于刪除指定目錄下的內容。

dir
切換到目錄。默認pipeline工作在工作空間目錄下，dir步驟可以讓我們切換到其它目錄。例如：dir("/var/logs") { deleteDir() }

fileExists
判斷文件是否存在。fileExists('/tmp/a.jar')判斷/tmp/a.jar文件是否存在。如果參數是相對路徑，則判斷在相對當前工作目錄下，該文件是否存在。結果返回布爾類型。

isUnix
判斷是否為類Unix系統。如果當前pipeline運行在一個類Unix系統上，則返回true。

pwd
確認當前目錄。pwd與Linux的pwd命令一樣，返回當前所在目錄。它有一個布爾類型的可選參數：tmp，如果參數值為true，則返回與當前工作空間關聯的臨時目錄。

writeFile
將內容寫入指定文件中。
writeFile支持的參數有：

• file：文件路徑，可以是絕對路徑，也可以是相對路徑。
• text：要寫入的文件內容。
• encoding（可選）：目標文件的編碼。如果留空，則使用操作系統默認的編碼。如果寫的是Base64的數據，則可以使用Base64編碼。

readFile
讀取指定文件的內容，以文本返回。
readFile支持的參數有：

• file：路徑，可以是絕對路徑，也可以是相對路徑。
• encoding（可選）：讀取文件時使用的編碼。

script {
    // "amVua2lucyBib29r" 是"jenkins book"進行Base64編碼后的值
    writeFile(file: "base64File", text: "amVua2lucyBib29r", encoding: "Base64")
    def content = readFile(file: "base64File", encoding: "UTF-8")
    echo "${content}"
    // 打印結果: jenkins book
}

2.5.2 制品相關步驟

stash
保存臨時文件。
stash步驟可以將一些文件保存起來，以便被同一次構建的其他步驟或階段使用。如果整個pipeline的所有階段在同一臺機器上執行，則stash步驟是多余的。所以，通常需要stash的文件都是要跨Jenkins node使用的。

stash步驟會將文件存儲在tar文件中，對于大文件的stash操作將會消耗Jenkins master的計算資源。Jenkins官方文檔推薦，當文件大小為5～100MB時，應該考慮使用其他替代方案。

stash步驟的參數列表如下：

• name：字符串類型，保存文件的集合的唯一標識。
• allowEmpty：布爾類型，允許stash內容為空。
• excludes：字符串類型，將哪些文件排除。如果排除多個文件，則使用逗號分隔。留空代表不排除任何文件。
• includes：字符串類型，stash哪些文件，留空代表當前文件夾下的所有文件。
• useDefaultExcludes：布爾類型，如果為true，則代表使用Ant風格路徑默認排除文件列表。

除了name參數，其他參數都是可選的。excludes和includes使用的是Ant風格路徑表達式。

unstash
取出之前stash的文件。
unstash步驟只有一個name參數，即stash時的唯一標識。通常stash與unstash步驟同時使用。以下是完整示例。

pipeline {
    agent none
    stages {
        stage('stash') {
            agent { label "master" }
            steps {
                script {
                    writeFile file: "a.txt", text: "$BUILD_NUMBER"
                    stash(name: "abc", include: "a.txt")
                }
            }
        }
        stage("unstash") {
            agent { label "node2" }
            steps {
                script {
                    unstash("abc")
                    def content = readFile("a.txt")
                    echo "${content}"
                }
            }
        }
    }
}

stash步驟在master節點上執行，而unstash步驟在node2節點上執行。

2.5.3 命令相關步驟

與命令相關的步驟其實是Pipeline：Nodes and Processes插件提供的步驟。由于它是Pipeline插件的一個組件，所以基本不需要單獨安裝。

sh
執行shell命令。
sh步驟支持的參數有：

• script：將要執行的shell腳本，通常在類UNIX系統上可以是多行腳本。
• encoding：腳本執行后輸出日志的編碼，默認值為腳本運行所在系統的編碼。
• returnStatus：布爾類型，默認腳本返回的是狀態碼，如果是一個非零的狀態碼，則會引發pipeline執行失敗。如果returnStatus參數為true，則不論狀態碼是什么，pipeline的執行都不會受影響。
• returnStdout：布爾類型，如果為true，則任務的標準輸出將作為步驟的返回值，而不是打印到構建日志中（如果有錯誤，則依然會打印到日志中）。除了script參數，其他參數都是可選的。

returnStatus與returnStdout參數一般不會同時使用，因為返回值只能有一個。如果同時使用，則只有returnStatus參數生效。

bat、powershell
bat步驟執行的是Windows的批處理命令。powershell步驟執行的是PowerShell腳本，支持3+版本。這兩個步驟支持的參數與sh步驟的一樣。

2.5.4 其他步驟

error
主動報錯，中止當前pipeline。
error 步驟的執行類似于拋出一個異常。它只有一個必需參數：message。通常省略參數：error（"there's an error"）。
tool
使用預定義的工具。
如果在Global Tool Configuration（全局工具配置）中配置了工具，那么可以通過tool步驟得到工具路徑。
tool步驟支持的參數有：

• name：工具名稱。
• type（可選）：工具類型，指該工具安裝類的全路徑類名。

每個插件的type值都不一樣，而且絕大多數插件的文檔根本不寫type值。除了到該插件的源碼中查找，還有一種方法可以讓我們快速找到type值，就是前往Jenkins pipeline代碼片段生成器中生成該tool步驟的代碼即可。

timeout
代碼塊超時時間。
為timeout步驟閉包內運行的代碼設置超時時間限制。如果超時，將拋出一個org.jenkinsci.plugins.workflow.steps.FlowInterruptedException異常。timeout步驟支持如下參數：

• time：整型，超時時間。
• unit（可選）：時間單位，支持的值有NANOSECONDS、MICROSECONDS、MILLISECONDS、SECONDS、MINUTES（默認）、HOURS、DAYS。
• activity（可選）：布爾類型，如果值為true，則只有當日志沒有活動后，才真正算作超時。

waitUntil
等待條件滿足。
不斷重復waitUntil塊內的代碼，直到條件為true。waitUntil不負責處理塊內代碼的異常，遇到異常時直接向外拋出。waitUntil步驟最好與timeout步驟共同使用，避免死循環。示例如下：

timeout(50) {
    waitUntil {
        script {
            def r = sh script: 'curl http://example', returnStatus: true
            retturn (r == 0)
        }
    }
}

retry
重復執行塊
執行N 次閉包內的腳本。如果其中某次執行拋出異常，則只中止本次執行，并不會中止整個retry的執行。同時，在執行retry的過程中，用戶是無法中止pipeline的。

steps {
    retry(20) {
        script {
            sh script: 'curl http://example', returnStatus: true
        }
    }
}

sleep
讓pipeline休眠一段時間。
sleep步驟可用于簡單地暫停pipeline，其支持的參數有：

• time：整型，休眠時間。
• unit（可選）：時間單位，支持的值有NANOSECONDS、MICROSECONDS、MILLISECONDS、SECONDS（默認）、MINUTES、HOURS、DAYS。

2.5.5 小貼士

1. Jenkins提供了一個pipeline代碼片段生成器，通過界面操作就可以生成代碼。（只有pipeline項目有“Pipeline Syntax菜單”）
2. VS Code擴展：Jenkins Pipeline Linter Connector，支持對Jenkinsfile的語法檢驗。
3. 使用Workspace Cleanup插件清理空間。
4. Ant風格路徑表達式。

Apache Ant樣式的路徑有三種通配符匹配方法，利用它們可以組合出多種路徑模式：

Ant風格路徑匹配實例：

需要注意的是，路徑匹配遵循最長匹配原則(has more characters)，例如/app/dir/file.jsp符合/**/*.jsp和/app/dir/*.jsp兩個路徑模式，那么最終就是根據后者來匹配。

參考資料：
[1] 《Jenkins 2.x實戰指南》
[2] https://jenkins.io/zh/doc/book/pipeline/syntax/
[3] https://jenkins.io/zh/doc/pipeline/steps/