How To: Parameterize Branch Name for Webhook

Some of our customers wish to pass Branch Name as a Jenkins input parameter for the Packager job so that a specific Datical Pipeline can be targeted. The below steps outline how this can be performed using the Generic Webhook Trigger Plugin.

Generic Webhook Trigger Pluggin

• https://plugins.jenkins.io/generic-webhook-trigger/

This plugin allows Jenkins access to the HTTP payload that triggered the build. Values, such as Branch name, can be extracted from the payload and used as filters and passed to Jenkins input parameters.

GitHub Instructions

1. In Jenkins, install the Generic Webhook Trigger Pluggin using Manage Jenkins → Manage Plugins

2. After installing the plugin you will see a checkbox under Build Triggers for Generic Webhook Trigger. Check the box to access the configurations.

   Open

   

    

3. In the Post content parameters add a variable, eg. ref. You will need to provide a JSONPath or XPath expression to extract the value from the HTTP payload.

   1. Sample HTTP payload from my Github webhook can be found here - SampleHttpPayload.json

   2. JSONPath evaluator can be found here - https://jsonpath.com/

   3. In this example we have two variables:

      • ref - value will be used to extract branch name from the SQL Repo triggering the webhook. JSONPath Expression: $.ref

      • author - value will be used to extract the author of the change. We need to exclude Jenkins user from triggering builds when Datical does the check-in at end of Packager process. JSONPath Expression: $.head_commit.author.name

      • Open

        

4. You will want to add a token. This token will be used when setting up the Webhook.

    

5. For debug/troubleshooting purposes Print post content and Print contributed variables. These settings will print the content of your HTTP payload and any variables you have specified above. You can turn them off later once everything is working.

   This logging will appear as below in the Jenkins console log:

   And

6. Optional filter

   1. Here is where you specify filters for the webhook. You can string together multiple filters. In this case we only want to trigger builds for the branch/pipelines named current and data_corrections. We do not want to trigger a build for master or any other branch name.

   2. Additionally we want to prevent builds from triggering when the check-in is performed by the Jenkins user named Admin.

   3. Expression:

      ^(?!.*Admin).*(refs\/heads\/current|refs\/heads\/data_corrections).*$

   4. Text: $ref $author

       

7. For the job’s Branch Input Parameter (here called ref) you can reference the parameters set in the Post content parameters section described above. Please note that Branch will need to be extracted from the ref value because ref is in the payload as eg. refs/heads/master or refs/heads/data_corrections.

    

8. In the Jenkinsfile to extract the Branch from the ref input value, add the following to the environment section:

   BRANCH="${params.ref}".substring("${params.ref}".lastIndexOf("/") + 1) PIPELINE="${BRANCH}"

9. Finally you will need to add your trigger to the GitHub SQL repository. Go to the specific SQL Repository → Settings → Webhooks → Add webhook

   1. Payload URL will be eg. http://dunder-mifflin.datical.net:8080/generic-webhook-trigger/invoke?token=abc

   2. Content type: application/json

   3. Configure which events you would like to trigger the webhook

      Note: if you have an error here for whatever reason, eg. there are no Jobs in Jenkins that match the parameters when setting up the webhook, GitHub seems to mark the webhook as in error. Updating an existing webhook marked in error does not “fix” the webhook. It will need to be deleted and a new webhook must be created.

10. Test your webhook setup by making a change to the desired branch and check if the webhook shows a Successful Delivery and Jenkins Build is started as expected:

     

BitBucket Instructions

1. In Jenkins, install the Generic Webhook Trigger Pluggin using Manage Jenkins → Manage Plugins

2. After installing the plugin you will see a checkbox under Build Triggers for Generic Webhook Trigger. Check the box to access the configurations.

    

3. In the Post content parameters add a variable, eg. BRANCH. You will need to provide a JSONPath or XPath expression to extract the value from the HTTP payload.

   1. Sample HTTP payload from my Bitbucket webhook can be found here - SampleHttpPayloadBitbucket.json

   2. JSONPath evaluator can be found here - https://jsonpath.com/

   3. In this example we have two variables:

      • BRANCH - value will be used to extract branch name from the SQL Repo triggering the webhook. JSONPath Expression: $.changes..refId

      • author - value will be used to extract the author of the change. We need to exclude Jenkins user from triggering builds when Datical does the check-in at end of Packager process. JSONPath Expression: $.actor.displayName

      •  

4. You will want to add a token. This token will be used when setting up the Webhook.

    

5. For debug/troubleshooting purposes Print post content and Print contributed variables. These settings will print the content of your HTTP payload and any variables you have specified above. You can turn them off later once everything is working.

   This logging will appear as below in the Jenkins console log:

    

   And

    

6. Optional filter

   1. Here is where you specify filters for the webhook. You can string together multiple filters. In this case we only want to trigger builds for the branch/pipelines named deploy-test1. We do not want to trigger a build for master or any other branch name.

   2. Additionally we want to prevent builds from triggering when the check-in is performed by the Jenkins user named Jenkins.

   3. Expression:

      ^(?!.*jenkins).*(refs\/heads\/deploy-test1).*$

   4. Text: $ref $author

       

7. For the job’s Branch Input Parameter (here called BRANCH) you can reference the parameters set in the Post content parameters section described above. Please note that Branch will need to be extracted from the parameter value because ref is in the payload as eg. refs/heads/master or refs/heads/deploy-test1.

    

8. In the Jenkinsfile to extract the Branch from the BRANCH input value, add the following to the environment section:

9. Finally you will need to add your trigger to the GitHub SQL repository. Go to the specific SQL Repository → Settings → Webhooks → Add webhook

   1. Payload URL will be eg. http://dunder-mifflin.datical.net:8080/generic-webhook-trigger/invoke?token=abc

   2. Content type: application/json

   3. Configure which events you would like to trigger the webhook

       

10. Test your webhook setup by making a change to the desired branch and check if the webhook shows a Successful Delivery and Jenkins Build is started as expected: