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，或掃描下面的二維碼添加關注：

作者： Surpassme

來源： http://www.jianshu.com/u/28161b7c9995/

http://www.cnblogs.com/surpassme/

宣告：本文著作權歸作者所有，歡迎轉載，但未經作者同意必須保留此段宣告，且在文章頁面明顯位置給出原文鏈接，否則保留追究法律責任的權利，如有問題，可發送郵件聯系，讓我們尊重原創者著作權，共同營造良好的IT朋友圈，

轉載請註明出處，本文鏈接：https://www.uj5u.com/qita/540016.html

標籤：其他

上一篇：淺析靜態應用安全測驗

下一篇：來自泰山運維的2022年終總結