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朋友圈。
【推荐】国内首个AI IDE,深度理解中文开发场景,立即下载体验Trae
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· 分享一个免费、快速、无限量使用的满血 DeepSeek R1 模型,支持深度思考和联网搜索!
· 25岁的心里话
· 基于 Docker 搭建 FRP 内网穿透开源项目(很简单哒)
· ollama系列01:轻松3步本地部署deepseek,普通电脑可用
· 按钮权限的设计及实现