此插件是针对JIRA以Jenkins的集成,主要是利用Jira的webhooks功能向jenkins发送相就通知,从而来触发jenkins的Job功能。
此插件是jenkins插件,需要安装在jenkins中。
此插件会有一下特性
- 接受任意http的请求,接收地址是:<J
ENKINS_URL>/generic-webhook-trigger/invoke
- 提供参数值
- 用这些值作为变量触发生成构建
只有当提供的正则表达式与提取的变量匹配时,才有触发作业的可选功能。下面是一个示例,假设内容如下所示:
{ "before": "1848f1236ae15769e6b31e9c4477d8150b018453", "after": "5cab18338eaa83240ab86c7b775a9b27b51ef11d", "ref": "refs/heads/develop" }
然后可以有一个变量,从post内容解析,名为ref,类型为JSONPath,表达式类似于$.ref。
可选的筛选文本可以设置为$ref,筛选regexp设置为^(refs/heads/develop | refs/heads/feature/+)$,以便仅为develop和feature分支触发生成。
触发特定的Job
在多个作业中使用该插件时,将具有相同的URL触发器所有作业。如果只想触发某个作业,则可以:
- 使用token参数可以为不同的作业使用不同的令牌。仅使用令牌意味着只有具有该确切令牌的作业才会对该请求可见。这将提高性能并减少每次调用的响应。
- 或者,添加一些请求参数(或Head,或post内容)并使用regexp筛选器仅在该参数具有特定值时触发。
Token参数
有一个特殊的token
标记参数。提供时,调用将仅触发具有该确切标记的作业。token
还允许在没有任何其他身份验证凭据的情况下调用。
Token可以根据位置不同有以下格式
The token can be supplied as a:
- Request parameter:
curl -vs http://localhost:8080/jenkins/generic-webhook-trigger/invoke?token=abc123 2>&1 |
---|
- Token header:
curl -vs -H "token: abc123" http://localhost:8080/jenkins/generic-webhook-trigger/invoke 2>&1 |
---|
- Authorization header of type Bearer :
|
---|
白名单
白名单可以在Jenkins全局配置页面中配置。白名单将阻止任何未在此列表中配置的对插件的请求。主机可以为空,以允许任何静态IP、CIDR或范围,规则可以如下:
|
---|
默认值
插件可以配置为默认值。如下所示:
但如果手动执行作业(或重播pipeline),则不会使用此默认值。因为插件根本不会被调用。您可以通过检查“this job is parametized”来解决这个问题,并添加一个与在插件中配置的参数同名的参数,如下所示:
现在,当您手动触发作业、重播pipeline以及使用插件触发作业时,都将使用此默认值!
预构建步骤
如果需要在预构建步骤(如git clone)中解析值,则需要添加与变量同名的参数。
Pipeline
插件安装后在pipeline也可以使用GenericTrigger指令完成相同的配置。
现在,我们创建一个普通的pipeline项目。代码如下
#!groovy pipeline { agent { node { label 'master' } } triggers { GenericTrigger( genericVariables: [ [key: 'ref', value: '$. ref'] ], token: 'secret' , causeString: ' Triggered on $ref' , printContributedVariables: true, printPostContent: true ) } stages { stage('GWT env') { steps { sh "echo $ref" sh "printenv" } } } }
注意:在创建完成后,需要手动执行一次, 这样pipeline的触发条件オ会生效。
然后我们用postman 发起一次 HTTP POST 请求。
GenericTrigger 触发条件由GWT插件提供。此触发条件可以说是GWT的所有内容。
GenericTrigger 触发条件分为5部分,这样更易于理解各参数的作用
- 从 HTTP POST 请求中提取参数值。
- token, GWT 插件用于标识Jenkins项目的唯一性。
- 根据清求参数值判断是否触发Jenkins项目的抗行。
- 日志打印控制。
- Webhook 响应控制。
一个 HTTP POST 请求可以从三个维度提取参数,即 POST Body、URL参数和header。
GWT 插件提供了三个参数分别从这三个维度的数据进行提取。
genericVariables: 提取POST body 中的参数
genericVariables: [ [ key: 'before', value: '$.before', expressionType: 'JSONPath', regularFilter: '', defaultValue: '' ], [key: 'ref', value: '$.ref'] ],
- value: JSONPath 或 XPath 表达式,取决于 expressType 参数值,用于从 POST body 中提取值。
- key: 从 POST Body 中提取出的值的新变量名,可用于pipeline其他步骤。
- expresssType: 可选, value的表达式类型,默认为JSONPath,当请求为XML内容时,必须指定 XPath 值。
- defaultValue:可选,当提取不到值,且defaultValue不为空时,则使用defaultValue作为返回值。
- regexpFilter:可选,过滤表达式,对提取出来的值进行过滤。regexpFilter做的事情其实就是
string.replaceAll(regexpFilter,"")
;。string是从HTTP请求中提取出来的值。
genericRequestVariables:从URL参数中提取值。
genericRequestVariables: [ [ key: 'requestWithNumber', regexpFilter: '[^0-9]', ], [key: 'requestWithString', regexpFilter: ''] ],
• key:提取出的值的新变量名,可用于pipeline其他步骤。
• regexpFilter:对提取出的值进行过滤。
genericHeaderVariables:从HTTP header 中提取值。
用法和genericRequestVariables一样。
token 参数
标识唯一性,值可以使用项目+时间
当Jenkins接收到 GWT 接口的请求时,会将请求代理给GWT插件处理。GWT插件内部会从Jenkins实例对象中取出所有的参数化Jenkins项目,包括pipeline, 然后进
行遍历。如果在参数化项目中GenericTrigger配置的token的值与Webhook请求时的token的值
致,则触发此参数化项目。
如果多个项目的此参数值一样,都会被触发。
GWT还可以根据我们提取出的值进行判断。示例如下:
- regexpFilterText:需要进行匹配的key。例子中,我们使用从POST body中提取出的refValue变量值。
- *regexpFilterExpression:正则表达式。
如果 regexpFilterText 参数的值符合 regexpFilterExpression 参数的正则表达式,则触发执行
打印内容
GWT 插件提供了三个供日调试打印日志的参数
- Silent response 当为true,只返回http 200 状态码,不返回触发结果
- Print post content 将 webhook 请求的内容打印到日志上
- Print contributed variables 将 提取后的变量打印到日志上
https://github.com/jenkinsci/generic-webhook-trigger-plugin