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

Jenkins

Plugins

Github

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`

GitHub Permissions and API token Scopes for Jenkins.

IMPORTANT:

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

Credential Kinds

Option 1: Secret Text - API Token (recommended)

  • Kind: Secret Text
  • Secret: GitHub API token for “GitHub-API-User” as explained in

Option 2: GitHub Username and Password - Letting the GitHub plugin to get API token for you.

  • Kind: Username and Password
  • Go to Advanced > Manage Additional GitHub Actions > Convert Login and Password to token
  • LIMITATION: Auto-creating token doesn’t work with GitHub 2FA.

Validate Credentials

Credentials can be validated 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

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.

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:

Have more questions? Submit a request

4 Comments

  • 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
Please sign in to leave a comment.