- How to configure GitHub webhooks for triggering jobs?
- How does GitHub webhooks for triggering jobs works for Pipeline Multibranch or GitHub Organization Folder?
- Cloudbees Jenkins Enterprise (CJE)
- GitHub plugin
- GitHub Pull Request Builder plugin
- CloudBees GitHub Pull Request Builder plugin
- Pipeline Multibranch Plugin
- GitHub Organization Folder Plugin
- Github Webhook
To understand the configuration, it is important to make a distinction regarding GitHub plugins direct dependency. Multibranch projects and Organization folders from GitHub depends directly on GitHub Branch Source Plugin and not the GitHub plugin.
1. At network level
At the network/infrastructure level, the Jenkins instance must be able to connect to GitHub and vice versa.
Note: If you are testing this feature running Jenkins locally, a tool such as ngrok might be helpful.
2. At Credential level
On the left hand side menu of the Jenkins Dashboard (Root) click on Credentials and then create a new Global > Secret Text Credential type, in the secret text introduce the API token of the user “GitHub-User-X” who will send “push” or “pull request” events to the “Repo X”.
To generate and API token, please review this KB about GitHub User Scopes and Organization Permission.
This credentials will be used by the Step 4: Configuration of the Github Plugin.
3. At Job level
Depending of the type of jobs:
A. None Multibranch pipelines plugins and GitHub Organization Folder
In the Job configuration, one of the following
Build Triggers needs to be selected :
- For PUSH events:
Build when a change is pushed to GitHub
- For PULL REQUEST events:
Build pull requests to the repository
- For triggering by PULL REQUEST events, one of the following plugins need to be installed: GitHub Pull Request Builder plugin or CloudBees GitHub Pull Request Builder plugin. However, PUSH events is enabled by the GitHub plugin.
- CloudBees GitHub Pull Request Builder plugin requires
Enable Git validated merge supportenabled.
- Both triggers can be selected together if it was needed in a Freestyle project. However
Build pull requests to the repositorytrigger option is not available for Pipeline jobs. Alternatively, use Multibranch Pipeline and restrict the branch to build in Advanced options >
Include branchesto just the master (a
Jenkinsfilein the master branch of the repo is needed).
B. Multibranch pipelines plugins and GitHub Organization Folder
It is all one process:
branch indexing, and it is configured by default, so nothing needs to configured for this aspect in the Jenkins side at job level.
branch indexing takes place for any
pull request events.
4. At WebHook level
Go to Manage Jenkins -> Configure System -> GitHub Plugin Configuration, add a new Github Server Config.
Pair of GitHub token (credentials generated on the Step 2) and server url. Credentials can be validated by clicking on
Verify credentials. If this credentials are fine the following output is expected on the GUI:
Verify credentials Credentials verified for user "GitHub-User-X", rate limit: 4994
If your Jenkins uses multiple repositories that are spread across different user accounts, you can list them all here as separate configs.
For API URL field, to use public github.com, leave this field to the default value of https://api.github.com. Otherwise if you use GitHub Enterprise, specify its API endpoint here (e.g., https://ghe.acme.com/api/v3/).
Depending on how the WebHook is managed
This option does not work for Pipeline Multibranch Plugin plugins or GitHub Organization Folder jobs, because it is inhered from the GitHub plugin and not the GitHub Branch Source plugin.
Jenkins generate the WebHook for you. For this option, check on
Manage hook URLs so it gets enabled.
On GitHub side , nothing needs to be done. Once the event triggers the build for the “Job X”, a webhook is automatically added on GitHub for “Repo X”. It includes the event which triggers the job ( Pull request or Push ). To check this go to the Setting button of the “Repo X” GitHub website > Service Hooks. Please, note that Jenkins will create one hook per different event.
This option works all types of jobs, including Multibranch pipelines plugins and GitHub Organization Folder.
For this option, on the Jenkins side, disable
Manage hook URLs
On the GitHub side, go to the GitHub repository and click on the Setting button. Then, create a new Service Hooks -> Post-Receive URLs and enter the URL of your Jenkins instance, which must be
https://<JENKINS_URL>/github-webhook/ - Don’t forget the last “/”.
- Content type should be set up as
- For PUSH events: Check
- For PULL REQUEST events:
Pull request. This option is available from the
Let me select individual eventsoption.
1. Each webhook can be installed on a Organization level (mandatory for GitHub Organization Folder jobs) or a Specific Repository. In any case, within a GitHub Organization, in order to access to Setting > WebHooks the Owner** role is needed.**
2. In case both events are needed, select both from
Let me select individual events. So, just one webhook can trigger different types of events.
The above image is showing the configuration for just for push events