GitHub webhook configuration

Issue

  • How to configure GitHub webhooks for triggering jobs?
  • How does GitHub webhooks for triggering jobs works for Pipeline Multibranch or GitHub Organization Folder?

Environment

  • Jenkins
  • 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

Resolution

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.

Secret text API token

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

Notes:

  1. 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.
  2. CloudBees GitHub Pull Request Builder plugin requires Enable Git validated merge support enabled.
  3. Both triggers can be selected together if it was needed in a Freestyle project. However Build pull requests to the repository trigger option is not available for Pipeline jobs. Alternatively, use Multibranch Pipeline and restrict the branch to build in Advanced options > Include branches to just the master (a Jenkinsfile in 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 push and 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

A. Automatically

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.

Github Plugin Configuration Auto

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.

Github Web hook auto

B. Manually

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

Github Plugin Configuration Manual

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 application/x-www-form-urlendcoded.
  • Events:
  • For PUSH events: Check Push
  • For PULL REQUEST events: Pull request. This option is available from the Let me select individual events option.

Notes:
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.

Github Web hook auto

The above image is showing the configuration for just for push events

References

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

1 Comments

Date Votes
  • 0
    Avatar
    Lee Meador

    Where these instructions talk about "Manage hook URLs", they are referring to a single check box that you can get to by doing (from a Master or Client Master only)

    Manage Jenkins > Configure System > GitHub > GitHub Servers and add one. Then you have to enter the GitHub URL, whether its at github.com or is an enterprise github instance with some local URL to your network.

    Then you have to enter credentials to allow access to the GitHub instance (and the credentials have to have admin permission (or maybe somewhat less) to be able to create the hook.

    But that only matters if you select the box "Manage hook URLs" because it won't try to use the credentials you entered on line n-1 if you you unselect the check box on line n. (The order is confusing if not utterly wrong.)

    Note that when I went to this page from Google without logging in, I did not see any images and that left the text-only content very confusing. Particularly mentioning "Manage hook URLs" without any context whatsoever. Its a little better with images but still doesn't tell how to get to the page.

    It is not intuitive that you go to add a build job and click to automatically build on a change but that doesn't work until you go to a whole different place in a different part of the web app to check a box and enter GitHub access info. But that is what this article describes.

Please sign in to leave a comment.