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，或扫描下面的二维码添加关注：

posted @ 2022-12-15 23:43 Surpassme 阅读(1241) 评论(0) 编辑收藏举报

刷新页面返回顶部

登录后才能查看或发表评论，立即登录或者逛逛博客园首页

相关博文：

· Jenkins实践指南-05-Jenkins pipeline 语法01

· Jenkins实践指南-07-pipeline 内置基础步骤

· Pipline语法

· 【Jenkins系列】-Pipeline语法全集

· 1.7W字 Jenkins 保姆级教程

阅读排行：
· Apifox不支持离线，Apipost可以！
· 历时 8 年，我冲上开源榜前 8 了！
· Trae 开发工具与使用技巧
· 通过 API 将Deepseek响应流式内容输出到前端
· 分享一个我遇到过的“量子力学”级别的BUG。

公告

昵称： Surpassme
园龄： 8年1个月
粉丝： 76
关注： 8

+加关注

2025年3月

日

一

二

三

四

五

六

Surpassme

不去努力就不会知道自己有多么优秀！