GitHub Integration: Webhooks

Article ID:224543927
3 minute readKnowledge base

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

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:

  • GitHub leave default API URL.

  • GitHub Enterprise change the API URL by its API endpoint (e.g. For "https://ghe.acme.com" and API version 3: "https://ghe.acme.com/api/v3/").

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 controller’s Log Recorders activated. This bundle will contain a stacktrace that will help the CloudBees Support troubleshoot your issue.

A.3 Manage hooks

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 on the type of jobs:

B.1 Non-Multibranch Jobs

B.2 Pipeline Multibranch

B.3 GitHub Organization Folder

C. Troubleshooting

Tested products/plugins version

The latest update of this article was tested with: