Devops with Jenkins and Generic Webhook Triggers

home

CI or Continuous Integrations is a practice related to DevOps Software Development where developers push and merge their code changes in a SCM or Source Control Management like Git from time to time. These pushes or merges trigger automated builds and tests are run. Jenkins in this picture is an Open Source Continuous Integration tool that is widely used by developers to automate the testing and deployment of applications or changes to an existing application.

A webhook is a mechanism which automatically triggers the build of a Jenkins project in response to commit pushed into a Git repository.

I recently faced a challenge while using GitHub webhooks to trigger a Jenkins build. The build would get triggered whenever any event occurs related to a Pull Request. This means if I have two separate jobs in Jenkins, both will get triggered, one which gets triggered when a PR or pull request is created, edited, or reopened and the other job which should get triggered when the PR is merged. Sure, there are ways to parse the payload coming from the webhook by making use of Jenkins shared libraries but, a simple way of achieving this can be done by utilizing Jenkins Generic Webhook Trigger plugin on Jenkins.

You can find out more about the Generic Webhook Trigger plugin from here

Let’s get started!

Prerequisites

  1. Create a Jenkins API token
  2. Using the Jenkins console, navigate to the user profile
  3. Under API token, click on ‘Add new Token’
  4. Generate the token with default name and save it
  5. Generate a Personal Access Token (PAT) from GitHub
  6. Navigate to user settings in GitHub console
  7. Select Developer settings from the settings
  8. Click on Personal access tokens and generate a new token
  9. Select repo, admin:repo_hook, and user as scopes
  10. Save the token
  11. Save the personal access token generated in step 2 in Jenkins credentials store
  12. Navigate to your Jenkins server url 
  13. Click on Manage Jenkins
  14. Under Security , click on Manage Credentials
  15. Select ‘Jenkins’ under ‘Stores scoped to Jenkins’ 
  16. Click on Global Credentials
  17. Select ‘Add Credentials’ from the left pane
  18. Set ‘Username with Password’ under Kind
  19. Scope should be set to Global
  20. Set the Username as GitHub username
  21. Set the Password as GitHub PAT and click on ‘OK’ 
  22. Set the ID for the secret
  23. First , a plugin called the Generic WebHook Trigger Plugin for Jenkins needs to be installed . Go to Manage Jenkins  – Plugin Manager – and install this plugin

Above prerequisites need to be set once only

Pipeline Configuration

1. Navigate to Jenkins using your server url  (https://jenkins….)

2. Under your target folder set the target pipeline which should get triggered when a pull request is merged, select New Item

3. Select Pipeline and set the name

4. Once created, click on Configure

5. Under General section

  • Select GitHub project and provide the GitHub repository URL
  • Select ‘this project is parameterized’ and set it as String Parameter . Set the name as ‘payload’ – The reason of setting this parameter is to save the payload exported from GitHub webhook in it. The payload can then be extracted by using ‘env.payload’ in the Jenkins pipeline

 6. Under ‘Build Triggers’ , select ‘Generic Webhook Trigger’

7. Add a ‘post content’ parameter with variable called ‘payload’ with a JSONPath type . This parameter will be used to receive the payload sent from GitHub webhook . The expression ‘$’ represents entire payload . The payload received is used by the parameter set in step 5

8. A second post content parameter needs to be added called ‘merged This parameter will check the pull request merged status (true or false) from the payload using an optional filter which will be configured in the next steps . GitHub payload can be broken down by opening up the JSON path using

https://isonpath.curiousconcept.com

The variable name for this parameter will be ‘merged’, type will be JSONPath, and expression will be set to ‘$pull request.merged’ which represents the pull request merged status extracted from the payload (true or false).

Create a Token after post content parameters. This token is unique for each job and helps the webhook trigger the right job when defined in the GitHub webhook’s payload url. The payload url defined in GitHub should look something like this: <a href=”https://<defaultname&gt;https://<defaultname&gt;:<Jenkins API token>@jenkins…..com /generic-webhook -trigger/invoke?token =<UNIQUE TOKEN>

e.g. UNIQUE TOKEN can be something like ‘configRepo-PR-merge’

Ignore the ‘Token credential’ and ‘Cause’ fields under this section

10. Under the ‘Optional filter’ set the expression as ‘true’ and in text, instead of a string, we can specify one of the variables set above. In this case, variable ‘action’ will be set as ‘$merged’

11. Under the Pipeline section (follow below steps if your pipeline will be running a script GitHub)

12. Select Pipeline Script from SCM under Definition

  • Set Git as SCM
  • Provide the GitHub Repository URL
  • Select the Credentials for GitHub login (this can be set in the Global credentials store)
  • Set */master as the Branch specifier
  • Select Default under Git Executable
  • Set ‘Auto’ in Repository browser
  • Under Script path, specify the path or Jenkinsfile name in GitHub repository

13. Click on Apply

Webhook creation

GitHub webhook creation involves the following steps.

  1. Navigate to the GitHub repository
  2. Under the settings tab, click on hooks
  3. Click on ‘Add webhook’
  4. The Payload URL should look like this: https://<defaultname&gt;:<JenkinsAPI token>@jenkins… .com/generic-webhook -trigger/invoke?token=<UNIQUE TOKEN>
  5. The first part of the payload URL is the API token generated in Jenkins: https :<defaultname>:<Jenkins API token>@jenkins… .com
  6. The last part of the URL (…generic-webhook-trigger/invoke?token=) involves a token which is the string value set under ‘post content parameters’ when configuring the pipeline in previous steps.
  7. The content type should be set as ‘application/json’
  8. Disable SSL verification
  9. Select ‘Let me select individual events’ under events section
  10. Select Pull requests

Now to test all this, simply create a Pull Request and check if the Jenkins job is triggered or not. Since we set the optional filter to be true if pull request is merged, creation of pull request should not trigger this job. Go ahead and merge the pull request. If it triggers the job, success!!!

Leave a comment