Plugin Information |
---|
View Generic Webhook Trigger on the plugin site for more information. |
This is a Jenkins plugin that can:
- Receive any HTTP request,
JENKINS_URL/generic-webhook-trigger/invoke
- Extract values
- Trigger a build with those values contribute as variables
There is an optional feature to trigger jobs only if a supplied regular expression matches the extracted variables. Here is an example, let's say the post content looks like this:
{ "before": "1848f1236ae15769e6b31e9c4477d8150b018453", "after": "5cab18338eaa83240ab86c7b775a9b27b51ef11d", "ref": "refs/heads/develop" }
Then you can have a variable, resolved from post content, named ref
of type JSONPath
and with expression like $.ref
. The optional filter text can be set to $ref
and the filter regexp set to ^(refs/heads/develop|refs/heads/feature/.+)$ to trigger builds only for develop and feature-branches.
There are more examples of use cases here.
Video showing an example usage:
It can trigger on any webhook, like:
- Bitbucket Cloud
- Bitbucket Server
- GitHub
- GitLab
- Gogs and Gitea
- Assembla
- Jira
- And many many more!
The original use case was to build merge/pull requests. You may use the Git Plugin as described in this blog post to do that. There is also an example of this on the Violation Comments to GitLab Plugin page.
You may want to report back to the invoking system. HTTP Request Plugin is a very convenient plugin for that.
If a node is selected, then all leafs in that node will be contributed. If a leaf is selected, then only that leaf will be contributed.
Trigger only specific job
When using the plugin in several jobs, you will have the same URL trigger all jobs. If you want to trigger only a certain job you can:
- Use the
token
-parameter have different tokens for different jobs. Using only the token means only jobs with that exact token will be visible for that request. This will increase performance and reduce responses of each invocation. - Or, add some request parameter (or header, or post content) and use the regexp filter to trigger only if that parameter has a specific value.
Token parameter
There is a special token
parameter. When supplied, the invocation will only trigger jobs with that exact token. The token also allows invocations without any other authentication credentials.
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 :
curl -vs -H "Authorization: Bearer abc123" http://localhost:8080/jenkins/generic-webhook-trigger/invoke 2>&1
Troubleshooting
If you want to fiddle with the plugin, you may use this repo: https://github.com/tomasbjerre/jenkins-configuration-as-code-sandbox
If you are fiddling with expressions, you may want to checkout:
- This JSONPath site
- This XPath site
- This regexp site Also syntax here.
It's probably easiest to do with curl
. Given that you have configured a Jenkins job to trigger on Generic Webhook, here are some examples of how to start the jobs.
curl -vs http://localhost:8080/jenkins/generic-webhook-trigger/invoke 2>&1
This should start your job, if the job has no token
configured and no security enabled. If you have security enabled you may need to authenticate:
curl -vs http://theusername:thepasssword@localhost:8080/jenkins/generic-webhook-trigger/invoke 2>&1
If your job has a token
you don't need to supply other credentials. You can specify the token
like this:
curl -vs http://localhost:8080/jenkins/generic-webhook-trigger/invoke?token=TOKEN_HERE 2>&1
If you want to trigger with token
and some post content, curl
can dot that like this.
curl -v -H "Content-Type: application/json" -X POST -d '{ "app":{ "name":"some value" }}' http://localhost:8080/jenkins/generic-webhook-trigger/invoke?token=TOKEN_HERE
Screenshots
Default values
The plugin can be configured with default values. Like below:
But if you execute the job manually (or replay a pipeline), this default value will not be used. Because the plugin will not be invoked at all. You can solve this by checking the "This job is parameterized" and add a parameter with the same name as the one you configured in the plugin. Like this:
Now this default value will be used both when you trigger the job manually, replaying pipeline, and when you trigger it with the plugin!
Pre build step
If you need the resolved values in pre build steps, like git clone, you need to add a parameter with the same name as the variable.
Job DSL Plugin
This plugin can be used with the Job DSL Plugin. There is also an example int he Violation Comments to GitLab Plugin wiki page.
Job DSL supports injecting credenials when processing the DSL. You can use that if you want the token
to be set from credentials.
pipelineJob('Generic Job Example') { parameters { stringParam('VARIABLE_FROM_POST', '') } triggers { genericTrigger { genericVariables { genericVariable { key("VARIABLE_FROM_POST") value("\$.something") expressionType("JSONPath") //Optional, defaults to JSONPath regexpFilter("") //Optional, defaults to empty string defaultValue("") //Optional, defaults to empty string } } genericRequestVariables { genericRequestVariable { key("requestParameterName") regexpFilter("") } } genericHeaderVariables { genericHeaderVariable { key("requestHeaderName") regexpFilter("") } } token('abc123') printContributedVariables(true) printPostContent(true) silentResponse(false) regexpFilterText("\$VARIABLE_FROM_POST") regexpFilterExpression("aRegExp") } } definition { cps { // Or just refer to a Jenkinsfile containing the pipeline script(''' node { stage('Some Stage') { println "VARIABLE_FROM_POST: " + VARIABLE_FROM_POST } } ''') sandbox() } } }
Pipeline
When configuring from pipeline (not multibranch pipeline), that pipeline needs to run once, to apply the plugin trigger config, and after that this plugin will be able to trigger the job. This is how Jenkins works, not something implemented in this plugin.
This means that if you create a pipeline like this:
You need to run it once to have the properties applied. You can verify that the properties has been applied by opening the configuration view (of view configuration if using multibranch pipeline) of the job. You will see that the "Generic Webhook Trigger" is checked and will now have values from your pipeline. Like this:
You can avoid having to run twice, by using Job DSL and have Job DSL create pipeline jobs with the plugin configured in that DSL.
This plugin can be used with the Pipeline Multibranch Plugin.
You can use the credentials plugin to provide the token
from credentials.
withCredentials([string(credentialsId: 'mycredentialsid', variable: 'credentialsVariable')]) { properties([ pipelineTriggers([ [$class: 'GenericTrigger', ... token: credentialsVariable, ... ] ]) ]) }
Perhaps you want a different token
for each job.
properties([ pipelineTriggers([ [$class: 'GenericTrigger', ... token: env.JOB_NAME, ... ] ]) ])
Or have a credentials string prefixed with the job name.
withCredentials([string(credentialsId: 'mycredentialsid', variable: 'credentialsVariable')]) { properties([ pipelineTriggers([ [$class: 'GenericTrigger', ... token: env.JOB_NAME + credentialsVariable, ... ] ]) ]) }
With a scripted Jenkinsfile like this:
node { properties([ pipelineTriggers([ [$class: 'GenericTrigger', genericVariables: [ [key: 'ref', value: '$.ref'], [ key: 'before', value: '$.before', expressionType: 'JSONPath', //Optional, defaults to JSONPath regexpFilter: '', //Optional, defaults to empty string defaultValue: '' //Optional, defaults to empty string ] ], genericRequestVariables: [ [key: 'requestWithNumber', regexpFilter: '[^0-9]'], [key: 'requestWithString', regexpFilter: ''] ], genericHeaderVariables: [ [key: 'headerWithNumber', regexpFilter: '[^0-9]'], [key: 'headerWithString', regexpFilter: ''] ], causeString: 'Triggered on $ref', token: 'abc123', printContributedVariables: true, printPostContent: true, silentResponse: false, regexpFilterText: '$ref', regexpFilterExpression: 'refs/heads/' + BRANCH_NAME ] ]) ]) stage("build") { sh ''' echo Variables from shell: echo ref $ref echo before $before echo requestWithNumber $requestWithNumber echo requestWithString $requestWithString echo headerWithNumber $headerWithNumber echo headerWithString $headerWithString ''' } }
With a declarative Jenkinsfile like this:
pipeline { agent any triggers { GenericTrigger( genericVariables: [ [key: 'ref', value: '$.ref'] ], causeString: 'Triggered on $ref', token: 'abc123', printContributedVariables: true, printPostContent: true, silentResponse: false, regexpFilterText: '$ref', regexpFilterExpression: 'refs/heads/' + BRANCH_NAME ) } stages { stage('Some step') { steps { sh "echo $ref" } } } }
It can be triggered with something like:
curl -X POST -H "Content-Type: application/json" -H "headerWithNumber: nbr123" -H "headerWithString: a b c" -d '{ "before": "1848f12", "after": "5cab1", "ref": "refs/heads/develop" }' -vs http://admin:admin@localhost:8080/jenkins/generic-webhook-trigger/invoke?requestWithNumber=nbr%20123\&requestWithString=a%20string
And the job will have this in the log:
Contributing variables:
headerWithString_0 = a b c
requestWithNumber_0 = 123
ref = refs/heads/develop
headerWithNumber = 123
requestWithNumber = 123
before = 1848f12
requestWithString_0 = a string
headerWithNumber_0 = 123
headerWithString = a b c
requestWithString = a string
Changelog
https://github.com/jenkinsci/generic-webhook-trigger-plugin/blob/master/CHANGELOG.md
20 Comments
Unknown User (kranthipolsani)
Does this plugin support https, can we use https://hostname:port/generic-webhook-trigger/invoke. I know it works when we use http url http://hostname:port/generic-webhook-trigger/invoke
Unknown User (tomasbjerre)
https://github.com/jenkinsci/generic-webhook-trigger-plugin/issues
Unknown User (carlososiel)
Exist any way to configure these plugin that allow when the job is triggered, these can use the jobs parameters wih default values?, I have a job with parameters, using default remote trigger I can use buildWithParameters. I need something similar, without send these values in the post body.
Unknown User (tomasbjerre)
https://github.com/jenkinsci/generic-webhook-trigger-plugin/issues
Unknown User (mploski)
Does this plugin can be used in declarative pipeline as well or only scripted is possible ?
Unknown User (tomasbjerre)
https://github.com/jenkinsci/generic-webhook-trigger-plugin/issues
Unknown User (gpwebresearch)
I want to trigger a job when a branch receives a merge. I know I can get the base branch and if merged:true but I do not know how to put those information in the GWT form. Typically we evaluate only one value but in this case it needs to check if it is this branch and received a merge.
Unknown User (tomasbjerre)
https://github.com/jenkinsci/generic-webhook-trigger-plugin/issues
Unknown User (gaborv)
Hi, really nice plugin!
One questions about this part:
"You may want to report back to the invoking system. HTTP Request Plugin is a very convenient plugin for that."
How can I report back to e.g. Github with this plugin that the build has passed / not passed in Jenkins? Do you maybe have some post aout this part?
Thanks!
Unknown User (tomasbjerre)
https://github.com/jenkinsci/generic-webhook-trigger-plugin/issues
Unknown User (gaborv)
This is not an issue, just a question.
Unknown User (tomasbjerre)
http://www.thesaurus.com/browse/issue
Unknown User (tomasbjerre)
https://github.com/jenkinsci/generic-webhook-trigger-plugin/issues
Unknown User (rvabdn)
This plugin is really usefull. I've managed to extract values from the post payload and use them to choose the correct branch to build from bitbucket. I'm trying to use those variables in my groovy script as part of the build but so far no luck. Has anyone managed to to that?
Unknown User (tomasbjerre)
https://github.com/jenkinsci/generic-webhook-trigger-plugin/issues
Unknown User (schniedergers)
I am using this with Github's webhooks, and would like to verify the signature (in X-Hub-Signature) of the request.
I'm able to compute the checksum on the request by extracting the payload via '$', but it does not contain the same whitespace as the original.
How can I get an exact copy of the payload within a pipeline, so that I can verify it against the X-Hub-Signature?
Unknown User (tomasbjerre)
https://github.com/jenkinsci/generic-webhook-trigger-plugin/issues
Unknown User (conchuir_ci)
Since upgrading this plugin my job on Jenkins does not queue more than one run when there is one already executing. My job receives all its input from a webhook, I have checked the webhook and it is receiving all the packages but the job will not queue more than one run regardless of how many packages come in at once. As a workaround I am using a second plugin that dynamically appends the date and time as a parameter to the job. This means that every run has a unique parameter and Jenkins allows more than one run to be queued. However I don't like having to use a second plugin and didn't have this problem before upgrading the plugin. Are you aware of this issue?
Unknown User (tomasbjerre)
https://github.com/jenkinsci/generic-webhook-trigger-plugin/issues/64
Unknown User (conchuir_ci)
Thanks Tomas this is what I needed.