Jenkins實踐指南-06-Jenkins pipeline 語法02

3.2.6 parameters

    [作者：Surpassme]parameters 又稱參數化，通過參數化可以決定pipeline運行期的行爲。pipeline主要支持兩種形式的參數化parameters命令參數化和插件參數化，這裏先介紹通過parameters的參數化形式，通過paramters命令參數化時，parameters僅允許放置在pipeline塊中

    Jenkins pipeline目前支持的參數化類型主要如下所示：

• string

    [作者：Surpassme]數據類型爲字符串類型，示例如下所示：

   parameters{
         string(name:"stringParaName",
                defaultValue:"stringDefaultValue",
                description:"string default description")
    }

• text

    [作者：Surpassme]數據類型爲多選文本類型，換行使用\n，示例如下所示：

   parameters{
        text(name:"textParaName",
             defaultValue:"dev\ntest\nrelease",
             description:"text default description"
        )
    }

• booleanParam

    [作者：Surpassme]數據類型爲布爾類型，示例如下所示：

   parameters{
        booleanParam(name:"boolParaName",
                     defaultValue:true,
                     description:"boolean default descripiton"
        )
    }

• choice

   [作者：Surpassme] 數據類型爲參數選擇類型，若存在多個選擇，可以使用\n或["paramsA","paramsB"]，示例如下所示：

   parameters{
        choice(name:"choiceParaName",
               choices:["dev","test","release"],
               description:"choice default description"
        )
    }

• password

    [作者：Surpassme]數據類型爲密碼類型，示例如下所示

   parameters{
        password(name:"passwordParaName",
                 defaultValue:"Surpass",
                 description:"password default description"
        )
    }

    實際工程項目中，參數不可能全部是單一類型的參數，pipeline中也可以支持定義多參數，示例如下所示：

    parameters{
        string(name:"stringParaName",
               defaultValue:"stringDefaultValue",
               description:"string default description")
        text(name:"textParaName",
             defaultValue:"dev\ntest\nrelease",
             description:"text default description"
        )
        booleanParam(name:"boolParaName",
                     defaultValue:true,
                     description:"boolean default descripiton"
        )
        choice(name:"choiceParaName",
               choices:["dev","test","release"],
               description:"choice default description"
        )
        password(name:"passwordParaName",
                 defaultValue:"Surpass",
                 description:"password default description"
        )
    }

在Jenkins pipeline中新增參數化後，至少要執行一次，才能被Jenkins加載生效，當再次執行時，就可以設置或選擇參數。

3.2.7 triggers

    [作者：Surpassme]triggers 用於定義運行pipeline的觸發器，根據觸發條件，又可以劃分爲時間觸發(主要包含 cron 和 pollSCM)和事件觸發(主要包含upstream和Webhook)兩個維度，詳細解釋如下所示：

triggers 僅能定義在pipeline塊下

• 時間觸發

    時間觸發是指定義一個時間，在到達指定時間後，運行pipeline

• 事件觸發

    事件觸發是指發生了某個事件後，再運行pipeline。例如，手動在界面上觸發、其他job觸發、HTTP API Webhook觸發等。

3.2.7.1 cron

   [作者：Surpassme] cron 觸發適用於週期性的job。例如每天執行job等。示例如下所示：

pipeline{
    agent any
    options{
        timestamps()
    }
    triggers{
        cron("*/1 * * * *")
    }
    stages{
        stage("cron demo"){
            steps{
                echo "running cron demo"
            }
        }
    }
}

    Jenkins triggers cron語法採用的是類似於Linux中的cron語法。一個cron包含5個字段，使用空格或Tab分隔，格式如下所示：

MINUTE HOUR DAY MONTH WEEK

    以上各個字段解釋如下所示：

• MINUTE： 代表分鐘，取值範圍爲0~59
• HOUR：代表小時，取值範圍爲1~23
• DAY：代表天數，取值範圍爲0~31
• MONTH：代表月份，取值範圍爲1~12
• WEEK：代表星期，取值範圍爲0~7，其中0和7代表星期天

對於DAY會有一些不準確的地方，因爲一個月有天數可能有28、29、30和31等

    以上爲基本用法，也可以使用一些特殊字符，一次指定多個值

• *：匹配所有值
• M-N：匹配M~N之間的值
• M-N/X或*/X:指定M~N之間的值，步長爲X
• A,B,...Z:使用逗號代表指定多個值

    在一些大型項目中，爲避免在同一時刻運行多個定時任務，造成負載過重，通常使用H(代表Hash)來避免出現此類問題。對於一些沒有必要精確到指定時間運行的任務，則通過使用H方式，示例如下所示：

H 22 * * *

以上這種寫法，則代表在0~59分鐘之間任何一個時間點執行

3.2.7.2 pollSCM

    [作者：Surpassme]pollSCM也稱輪詢代碼倉庫，是指定定期到代碼倉庫詢問代碼是否有變化，如果有變化，則執行pipeline。示例如下所示：

pipeline{
    agent any
    options{
        timestamps()
    }
    triggers{
        pollSCM("*/1 * * * *")
    }
    environment{
	   SUB_DIR_PATH="SURPASS_TEST"
	   GitURL="https://gitlab.surpassme.com/jenkins/surpassme_test.git"
	}
    parameters{
       gitParameter(name:"REGISTORY_TAG_BRANCH_NAME",
					type:"PT_BRANCH_TAG",
					branchFilter: "origin/(.*)",
					defaultValue: "master",
					selectedValue: "DEFAULT",
					sortMode:"DESCENDING_SMART",
					useRepository:"https://gitlab.surpassme.com/jenkins/surpassme_test.git",
					description: "please choose registory branch or tag")
    }
    stages{
        stage("pull code"){
            steps{
               checkout([
					$class:"GitSCM",
					branches:[[name:"${params.REGISTORY_TAG_BRANCH_NAME}"]],
					doGenerateSubmoduleConfigurations: false,
					extensions: [[$class:"RelativeTargetDirectory",relativeTargetDir:"${env.SUB_DIR_PATH}"]],
					gitTool: "Default",
					submoduleCfg: [],
					userRemoteConfigs:[[credentialsId:"	5fa35f44-8ad0-4c82-9d27-481a03ef6c7d",url:"${env.GitURL}"]]
				   ]
			   )
            }
        }
        stage("pollSCM demo"){
            steps{
                echo "running pollSCM demo"
            }
        }
    }
}

在實際應用時，如果代碼有變化，一般是由代碼倉庫主動通知Jenkins，若由Jenkins去頻繁代碼倉庫檢查，一是不好定義輪詢時間，二也會加重代碼倉庫的負擔。一般不推薦使用這種方式。

3.2.7.3 upstream

    [作者：Surpassme]當任務B的運行需要依賴任務A的運行結果時，則任務A稱之爲任務B的上游任務。upstream主要功能是讓任務B自行決定依賴哪些上游任務。示例如下所示：

pipeline{
    agent any
    triggers{
        upstream(upstreamProjects:"09-ParamtersSimple,10-cronSample",
                 threshold:hudson.model.Result.SUCCESS
            )
    }
    stages{
        stage("upsteam demo"){
            steps{
                echo "stream demo"
            }
        }
    }
}

    運行結果如下所示：

    以上參數詳細解釋如下所示：

• upstreamProjects：觸發的上游任務名稱，當接收多個上游任務時使用,分隔。
• threshold：觸發的上游任務運行結果，是一個枚舉類型，主要包含以下值
    - ABORTED： 任務被手動中止
    - FAILURE： 任務運行失敗
    - SUCCESS: 任務運行成功
    - UNSTABLE: 任務運行不穩定，存在一些錯誤，但不會導致任務運行失敗
    - NOT_BUILT: 多階段構建時，前面階段的問題導致後面階段無法運行

3.2.7.4 Webhook

    [作者：Surpassme]通過Webhook來觸發，一般又可以分爲Gitlab觸發和通用觸發。

3.2.7.4.1 GitLab觸發

    GitLab觸發一般是當GitLab發現代碼倉庫有變化時，觸發Jenkins來執行pipeline，利用這個特性能夠較好的解決pollSCM所帶來的問題。

3.2.7.4.1.1 GitLab 手動觸發

    以下來演示手動如何創建GitLab觸發的過程，步驟如下所示：

GitLab手動觸發需要的插件爲GitLab和Git

• 1.配置需要GitLab觸發的pipeline 任務，打開以下開關並進行配置

Jenkins暴露的Webhook地址格式一般爲：http://jenkins-master-address/project/<項目名>

• 2.基於安全考慮，一般會使用帶Token的訪問。點擊高級按鈕，生成Secret token

• 3.在GitLab配置通知Jenkins

• 4、測試是否成功

3.2.7.4.1.2 GitLab pipeline觸發

    [作者：Surpassme]對於手動配置GitLab Webhook也非常簡單，但卻不適合批量部署使用，其實通過Jenkinsfiles也可以實現。示例如下所示：

pipeline{
    agent any
    triggers{
        gitlab(triggerOnPush:true,
               triggerOnMergeRequest:true,
               branchFilterType:"All",
               secretToken:"232414e2f208ae6c9b26f455c7c1937f"
            )
    }
    stages{
        stage("GitLab trigger demo"){
            steps{
                echo "GitLab trigger demo"
            }
        }
    }
}

    GitLab trigger主要參數配置如下所示：

• triggerOnPush

    [作者：Surpassme]當GitLab產生push事件時，觸發運行pipeline

• triggerOnMergeRequest

    當GitLab觸發mergeRequest事件時，觸發運行pipeline

• branchFilterType

    爲必選參數，只有符合條件的分支才允許運行pipeline。可設置值爲：
    - NameBasedFilter: 基於分支名進行過濾，多個分支名使用,分隔
    - RegexBasedFilter: 基於正則表達式對分支名進行過濾
    - All: 所有分支都會被觸發

• secretToken

    訪問Jenkins的Token，可以使用隨機字符串工具生成

3.2.7.4.2 通用觸發

    [作者：Surpassme]前面主要使用的GitLab插件來配置觸發，但如果不是GitLab也是可以配置觸發。安裝插件Generic Webhook Trigger(https://plugins.jenkins.io/generic-webhook-trigger/)，在安裝Generic Webhook Trigger插件後，Jenkins會暴露一個API接口(http://jenkins-master-address/generic-webhook-trigger/invoke)來處理此API的語法。示例如下所示：

pipeline{
    agent any
    options{
        timestamps()
    }
    triggers{
        GenericTrigger(
             genericVariables:[
                   [
                    key:'ref',
                    value:'$.ref'
                   ]
                 ],
             causeString:'Triggered on $ref',
             token:"232414e2f208ae6c9b26f455c7c1937f",
             tokenCredentialId: "",
             printContributedVariables: true,
             printPostContent: true,
             silentResponse: false,
             shouldNotFlattern: false,
             regexpFilterText: '$ref',
             regexpFilterExpression: "refs/heads/"
            )
    }
    stages{
        stage("generic trigger webhook demo"){
            steps{
                echo "generic trigger webhook demo"
                sh "echo $ref"
            }
        }
    }
}

    注意事項如下所示：

• 1.需要注意引號的使用，這裏單雙引號還是有區別的
• 2.在配置完成後，需要手動運行一次，以便讓配置生效

    以下我們可以發送一個HTTP請求，來驗證效果，如下所示：

    運行結果如下所示：

3.2.8 when

    [作者：Surpassme]when 命令允許pipeline在滿足指定的條件時，才執行某個階段。使用when指令的注意事項如下所示：

• 使用when指令至少要包含一個條件
• when指令裏面若包含多個條件，則所有子條件都滿足才能執行某個階段
• when指令可以結合not、allOf、anyOf等來滿足更加靈活的條件匹配

3.2.8.1 單個條件

    [作者：Surpassme]單個條件的主要使用用法如下所示：

• branch

    當構建分支與給定的分支匹配，則執行該階段，示例如下所示：

pipeline{
    agent any
    stages{
        stage("branch release"){
            when{
                branch "release"
            }
            steps{
                echo "build on branch release"
            }
        }
        stage("branch test"){
            when{
                branch "test"
            }
            steps{
                echo "build on branch test"
            }
        }
    }
}

branch 僅適用於多分支pipeline

• changelog

    [作者：Surpassme]如果代碼倉庫的changlog符合相應的正則表達式，則執行某個階段，示例如下所示：

pipeline{
    agent any
    stages{
        stage("changlog demo"){
            when{
                changelog  '.*^\\[DEPENDENCY\\] .+$'
            }
            steps{
                echo "build on changelog"
            }
        }
    }
}

• changeset

    [作者：Surpassme]如果代碼倉庫變更集合中包含一個或多個文件符合給定的Ant風格路徑表達式，則執行某個階段，示例如下所示：

pipeline{
    agent any
    stages{
        stage("changeset demo"){
            when{
                changeset  "**/*.go"
            }
            steps{
                echo "build on changeset"
            }
        }
    }
}

• environment

    [作者：Surpassme]當環境變量的值與給定的值相同時，則執行某個階段，示例如下所示：

pipeline{
    agent any
    environment{
        NAME="Surpass"
    }
    stages{
        stage("environment demo"){
            when{
                environment name:"NAME",value:"Surpass"
            }
            steps{
                echo "build on environment"
            }
        }
    }
}

• equals

    [作者：Surpassme]當給定的值與期望值相等進，則執行某個階段，示例如下所示：

pipeline{
    agent any
    parameters{
        string(name:"name",
               defaultValue:"Surpass",
               description:"test name"
            )
    }
    stages{
        stage("equals demo"){
            when{
                equals actual: "${params.name}" ,expected:"Surpass"
            }
            steps{
                echo "build on equals"
            }
        }
    }
}

• expression

    [作者：Surpassme]如果表達式返回爲true時，則執行某個階段，示例如下所示：

pipeline{
    agent any
    parameters{
        string(name:"name",
               defaultValue:"Surpass",
               description:"test name"
            )
    }
    stages{
        stage("expression demo"){
            when{
                expression {
                    return params.name == "Surpass"
                }
            }
            steps{
                echo "build on expression"
            }
        }
    }
}

當表達式返回的是字符串時，必須轉換爲boolean類型或null，否則所有字符串會按 true 處理

• tag

    [作者：Surpassme]如果代碼倉庫的Tag與給定的Tab值匹配時，則執行某個階段，示例如下所示：

pipeline{
    agent any
    stages{
       stage("tag demo"){
            when{
               tag "Surpass-v3.*"
            }
            steps{
                echo "build on tag"
            }
        }
    }
}

    tag支持comparator參數，如下所示：

• EQUALS: 文本比較

pipeline{
    agent any
    stages{
       stage("tag demo"){
            when{
               tag pattern:"Surpass-v3.3.1",comparator:"EQUALS"
            }
            steps{
                echo "build on tag"
            }
        }
    }
}

• GLOB：默認值，Ant風格路徑表達式，因其是默認值，完整寫法如下所示：

pipeline{
    agent any
    stages{
       stage("tag demo"){
            when{
               tag pattern:"Surpass-v3.3.1",comparator:"GLOB"
            }
            steps{
                echo "build on tag"
            }
        }
    }
}

• REGEXP：正則表達式

pipeline{
    agent any
    stages{
       stage("tag demo"){
            when{
               tag pattern:"Surpass-v\\d.*",comparator:"REGEXP"
            }
            steps{
                echo "build on tag"
            }
        }
    }
}

• not

    [作者：Surpassme]當條件不滿足時，則執行某個階段，示例如下所示：

pipeline{
    agent any
    stages{
       stage("tag demo"){
            when{
               not {
                   tag pattern:"Surpass-v\\d.*",comparator:"REGEXP"
               }
            }
            steps{
                echo "build on tag"
            }
        }
    }
}

3.2.8.2 組合條件

    [作者：Surpassme]組合條件的主要使用用法如下所示：

• allOf

    [作者：Surpassme]當所有條件都滿足時，才執行該階段，示例如下所示：

pipeline{
    agent any
    environment{
        NAME="Surpass"
    }
    parameters{
        string(name:"name",
               defaultValue:"Surpass",
               description:"test allOf"
        )
    }
    stages{
       stage("allOf demo"){
            when{
               allOf {
                   environment name:"NAME",value:"Surpass"
                   expression {
                        return params.name == "Surpass"
                   }
               }
            }
            steps{
                echo "build on allOf"
            }
        }
    }
}

• anyOf

    [作者：Surpassme]當任意一個條件都滿足時，才執行該階段，示例如下所示：

pipeline{
    agent any
    environment{
        NAME="Surpass"
    }
    parameters{
        choice(name:"name",
               choices:["dev","test","release"],
               description:"test anyOf"
            )
    }
    stages{
       stage("anyOf demo"){
            when{
               anyOf {
                   environment name:"NAME",value:"Surpass"
                   expression {
                        return params.name == "test"
                   }
               }
            }
            steps{
                echo "build on anyOf"
            }
        }
    }
}

3.2.9 agent

    [作者：Surpassme]Jenkins 採用的是master+agent架構，master負責提供界面，處理HTTP請示和管理構建環境等。具體的構建執行，則由agent負責。基於此，只需要增加agent就可以支持更多的項目同時運行。

3.2.9.1 添加agent標籤

    [作者：Surpassme]當 agent 數量較多時，爲了快速辨別和使用不同的agent，我們就需要對agent添加標籤。通過標籤可以將多個agent分配到同一個邏輯組中。同一個agent也支持多個標籤。標籤的命名注意事項如下所示：

標籤中不能包含空格、!、&、|、<、>、(、)等特殊字符

    添加標籤時，可以參考以下幾個維度進行增加

• 工具鏈：JDK8、Node.js、Python3、Goland、Kubernetes
• 操作系統：Windows10、Linux、MacOS

    添加agent標籤的示例如下所示：

3.2.9.2 agent 標籤使用

    [作者：Surpassme]agent 部分描述的是整個pipeline或特定階段時，使用哪一個agent運行任務。即Jenkins master 會根據agent標籤，將具體的任務分配到滿足匹配標籤的agent上。因此agent必做在pipeline塊內的頂部定義，stage塊內的定義是可選的。其詳細使用如下所示：

• any

    any 表示任何可用的agent都可以運行任務，示例如下所示：

pipeline{
   agent any
   // ...
}

agent 定義在pipeline的頂部

pipeline{
   agent any // 不能省略
   stages{
     stage("build"){
        agent any // 定義在階段內部
        steps{
           echo "build demo ..."
        }
     }
   }
}

agent 定義在stage內部

• 通過標籤指定agent

    [作者：Surpassme]當需要指定任務運行在CentOS 7中時，可以通過agent來指定標籤，示例如下所示：

pipeline{
    agent {
        label "centos7"
    }
    stages{
        stage("agent label demo"){
            steps{
                echo "agent label demo"
            }
        }
    }
}

• none

    [作者：Surpassme]如果不想分配agent，則可以使用none，示例如下所示：

pipeline{
    agent none
    stages{
        stage("agent label demo"){
            agent{
                label "centos7"
            }
            steps{
                echo "agent label demo"
            }
        }
    }
}

這種場景一般常用於希望各個stage運行在不同的agent中

3.2.10 post

    [作者：Surpassme]post部分主要用於在整個pipeline或階段完成後的一些附加步驟，是可選的。根據pipeline或階段完成狀態，post部分可分成多個條件塊，如下所示：

• always：不論當前完成狀態是什麼均執行
• changed：只要當前狀態與上一次完成狀態不同就執行
• fixed：上一次完成狀態爲失敗或不穩定，當前完成狀態爲成功時執行
• regression：上一次完成狀態爲成功，當前完成狀態爲失敗，不穩定或中止時執行
• aborted：當前執行結果是中止狀態時執行
• failure：當前完成狀態是失敗時執行
• success：當前完成狀態是成功時執行
• unstable：當前完成狀態爲不穩定進執行
• cleanup：清理條件。不論當前完成狀態是什麼，在其他所有條件塊執行完成後都執行

    示例如下所示：

pipeline{
    agent any
    options{
        timestamps()
    }

    stages{
        stage("pull code"){
            steps{
                echo "pull code"
            }
            post{
                failure{
                    echo "pull code failed,please check"
                }
            }
        }

        stage("build"){
            steps{
                echo "build ..."
            }
            post{
                regression{
                    echo "build regression"
                }
            }
        }

        stage("deploy"){
            steps{
                echo "deploy"
                script{
                    error(message:"deploy error")
                }
            }
            post{
                success{
                    echo "deploy success"
                }
                failure{
                    echo "deploy failure"
                }
            }
        }
    }
    post{
       aborted{
           echo "pipeline aborted"
       }
       unstable{
           echo "piepline unstable"
       }
       failure{
           echo "pipeline failure"
       }
       success{
           echo "pipeline success"
       }
       always{
           echo "ignore pipeline status,alway run print this section"
       }
    }
}

    [作者：Surpassme]運行結果如下所示：

原文地址：https://www.jianshu.com/p/55e918edf71f

本文同步在微信訂閱號上發佈，如各位小夥伴們喜歡我的文章，也可以關注我的微信訂閱號：woaitest，或掃描下面的二維碼添加關注：