GitHub Integration: Webhooks

Issue

  • How to integrate GitHub (and/or GitHub Enterprise) with Jenkins.
  • I would like to trigger Jenkins jobs from GitHub (and/or GitHub Enterprise) from a “GitHub API User” (GitHub User to interact with Jenkins).

Environment

Resolution

A. Plugin configuration

Go to Manage Jenkins > Configure System > GitHub section > Add a new GitHub Server Config

Add GitHub server/s managed by this Jenkins instance. So, if your Jenkins instance uses multiple repositories that are spread across different user accounts, you can list them all here as separate configs.

GitHub Plugin Configuration Auto

A.1 API URL

Two options:

A.2 Credentials

About Credentials

  1. You need Credentials for each of the GitHub/GitHub Enterprise Server added here.
  2. Jenkins needs a Personal API token to interact with the GitHub via webhooks.
    This token can be either created manually or automatically (see next section).
  3. Credentials from User: Admin permissions are required at the repository level but Owner role is required to create it at Organization level; For updating commit statuses / reading the list of collaborators, Write permission is required.

You can find more information on the GitHub token permissions in GitHub Permissions and API token Scopes for Jenkins.

Setting up the Credentials

As explained in the previous section, the plugin needs a token to work. You can choose to let Jenkins create the token on your behalf, or create it manually.

  • Let Jenkins create the token: this option is only available if you are not using two-factor authentication.
    You can make Jenkins generate the token by going to Advanced > Manage Additional GitHub Actions > Convert Login and Password to token.

  • Generate the token yourself: first generate a token (make sure to read the previous section to understand what rights to grant). Then in the Credentials section (under the API URL) create a Credential of type Secret Text and put the token you generated as a secret text.

You can then validate everything works as expected by clicking on Test Connection. If the credentials are correct a similar output to the following is expected:

Verify credentials
Credentials verified for user "GitHub-API-User", rate limit: 4994

Pay attention to the “GitHub API User” Rate limits.

In case of an error in the validation, make sure to take a Support Bundle right away with the Master Log Recorders activated.
This bundle will contain a stacktrace that will help the CloudBees Support troubleshoot your issue.

A.3 Manage hooks

Automatic Mode (Recommended)

Manage hooks: enabled

Jenkins create hooks in GitHub for you.

Manual Mode

Manage hooks: disabled

IMPORTANT: In this mode, you’ll be responsible for creating the webhook in GitHub under the following premises

B. Job Configuration

IMPORTANT: We recommend Multibranch Pipeline Jobs or GitHub Organization Folders.

Alternatively, you can use External HTTP Endpoints and define a eventTrigger per Jenkinsfile in each of the repo branches you wish to set the webhook (See this example). It offers more flexibility to filter the event information (payload) which triggers a build.

Depending of the type of jobs:

B.1 Non-Multibranch Jobs

See GitHub Webhook: Non-Multibranch Jobs

B.2 Pipeline Multibranch

See GitHub Webhook: Pipeline Multibranch

B.3 GitHub Organization Folder

See GitHub Webhook: Organization Folder

C. Troubleshooting

Troubleshooting guide

Tested products/plugins version

The latest update of this article was tested with:

Was this article helpful?
0 out of 0 found this helpful

Have more questions?

9 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.

  • 0
    Avatar
    Julien Carsique

    "Build when a change is pushed to GitHub" has been oddly reworded to "GitHub hook trigger for GITScm polling" by https://github.com/jenkinsci/github-plugin/pull/162

    In the mean time, the build behavior seems changed and not controllable from Jenkins anymore.

    Edited by Julien Carsique
  • 0
    Avatar
    Gene Ratzlaff

    Typo in section 3A.- : "None Multibranch"  should be Non-Multibranch?

    As of Jenkins 2.73.3:

    "Manage hook URLs" checkbox is now "Manage hooks", and my experience agrees with @Carsique: it doesn't seem to matter what you set it to, you still have to go to GitHub and input your webhook URL. Names have changed in GitHub, too (I'm using GitHub Enterprise):

    Since the automatic "Manage hooks" doesn't work, go to the GitHub repository you are working with, select Setting > Hooks & services.
    Select "Add webhook"
    In the "Payload URL" field, enter your  httpx://<JENKINS_URL>/github-webhook/ url.
    "Content type" - doesn't matter.
    "Secret" - I left this blank.
    "Just the push event." - trigger event
    "Active" - checkbox filled.
    Then select green "Add webhook" button.

    FWIW, instead of adding a webhook, I tried adding the Jenkins (Git plugin) service on the GitHub Settings>Hooks & services page. It didn't work for me.

    Edited by Gene Ratzlaff
  • 0
    Avatar
    Carlos Rodriguez Lopez

    @Lee Meador, @Julien Carsique, @Gene Ratzlaff. 

    We have recently updated this article. Please let us know if you find it clearer or you have found any issues.

    Regards,

     

    Edited by Carlos Rodriguez Lopez
  • 0
    Avatar
    Lee Meador

    "auto creating token does not work ..."

    But no instructions on how to create the token by hand are given.

  • 0
    Avatar
    Carlos Rodriguez Lopez

    Hi Lee Meador

    > But no instructions on how to create the token by hand are given.

    In case it does not work for you, create your own API token as explained in https://github.com/blog/1509-personal-api-tokens

    Regards

  • 0
    Avatar
    Deepti Singh

    Hi, as I go through it I found topic named: 

    A.3 Manage hooks

    Automatic Mode (Recommended)


    In this whats exactly Automatic mode and we can set it to enabled, if we use multi-branch pipeline how we can proceed with hook triggering.

     

    Edited by Deepti Singh
  • 0
    Avatar
    Christian Pinto

    Hi,

    is there a way to perform a different action from a Jenkinsfile according to the specific event received via webhook? Like differentiating the actions taken if the event is a push or a deployment, etc.

     

    Thanks,

    Christian

  • 0
    Avatar
    Carlos Rodriguez Lopez

    Hi,

    @Deepti Singh

    If we use multi-branch pipeline how we can proceed with hook triggering.

    Multibranch Pipelines and Github Organization Folders create webhooks automatically as long as you configured the job and GitHub plugin correctly as explained in the guide.

    @Christian Pinto

    is there a way to perform a different action from a Jenkinsfile according to the specific event received via webhook? Like differentiating the actions taken if the event is a push or a deployment, etc.

    CloudBees offers the External HTTP Endpoint feature which might help you with this request. Look at this example.

    Best Regards,

    Edited by Carlos Rodriguez Lopez
Please sign in to leave a comment.