GitHub/Jenkins: Setting up Webhooks
Contents
What is a webhook?
A webhook is a mechanism to automatically trigger the build of a Jenkins project upon a commit pushed in a Git repository.
In order for builds to be triggered automatically by PUSH and PULL REQUEST events, a Jenkins Web Hook needs to be added to each GitHub repository. You need admin permissions on that repository.
This guide details the steps to have Jenkins automatically create a build if it detects changes to a GitHub repository. This can be a very useful improvement to continuous integration setup with Jenkins because this method is only telling Jenkins to attempt a new build when a change is detected rather than polling on an interval, which can be a very inefficient.
For more information, see https://developer.github.com/webhooks/.
GitHub Plugin on Jenkins (only for Jenkins admins)
The GitHub plugin (https://plugins.jenkins.io/github) must be installed on Jenkins. This will give us the ability to configure Jenkins to use our GitHub repository.
Go in the page: Manage Jenkins -> Configure System -> GitHub:
Build project configuration
In Jenkins, under the project settings page "Source Code Management":
- set option to "Git",
- provide URL to your repo (e.g. https://github.com/d4science/gx-rest.git),
- set the credentials to git.gcube (only if the repository is NOT public),
- specify */master as branch to build,
The next step is to tell Jenkins to build when the Github hook is called. In the "Build Triggers" section:
- check "GitHub hook trigger for GITScm polling"
- check "Poll SCM" option with no schedule defined. This setup basically tells Jenkins to poll your GitHub repo only when requested via the webhook.
Webhook on the GitHub repository
For each GitHub repository or organization that you need to configure, perform the following steps:
- Navigate to the “Settings” tab.
- Select the “Webhooks” option on the left menu
- Click “Add Webhook”
In the Webhook form:
- For “Payload URL”:
- Use the address for the gCube Jenkins server instance: https://jenkins.d4science.org/github-webhook/
- Make sure to include the last /!
- Select “application/json” as the encoding type
- Leave “Secret” blank (unless a secret has been created and configured in the Jenkins “Configure System -> GitHub plugin” section)
- Select “Let me select individual events”
- Enable Pushes event
- Enable Pull Requests event
- Make sure “Active” is checked
- Click “Add Webhook” or “Update Webhook”
Jenkins will now receive push and pull request notifications for that repository, and related builds will be automatically triggered.
See https://help.github.com/en/github/extending-github/about-webhooks.
Testing the GitHub/Jenkins round trip
1) We push a new commit with a message "Update README.md" in the GitHib repository:
2) If the webhook has been properly set up, on the Jenkins interface we should see that the build of the linked project has started:
3) Clicking on the ongoing build, we can appreciate that it has been triggered by the commit:
4) Projects configured downstream will be also built if the build completes successfully.
Back to the CI guide.
