Using GitHub App authentication

There are several reasons for considering this authentication approach including:

  • The rate limit for a GitHub App scales with your organization size, whereas a user based token has a limit of 5000 requests per hour, regardless of how many repositories you have.

  • For organizations that have 2-factor authentication enforced - with GitHub Apps there is no need to manage 2 factor authentication tokens for a 'bot' user.

  • Jenkins GitHub Apps require a minimal, controlled set of privileges compared to a service user and its personal access token.

GitHub App authentication can be used with Multibranch Pipeline jobs, Organization folders, and Shared Libraries. It it not available for regular Pipeline or Freestyle jobs.

Setting up GitHub App authentication requires several steps in both GitHub and Jenkins. Complete the following steps in GitHub:

Afterwards, complete the following steps in Jenkins:

Supported versions

GitHub App authentication is available on the following versions and platforms:

  • CloudBees Core on modern cloud platforms version 2.222.4.3 (and higher)

  • CloudBees Core on traditional platforms version 2.222.4.3 (and higher)

  • GitHub Branch Source plugin version 2.7.1 (or higher)

Prerequisites

The following permissions are required to set up GitHub App authentication:

GitHub

Permission to create a GitHub App

CloudBees Core

Permissions to create a new credential and update job configurations:

  • Credentials/Create

  • Job/Configure

Creating the GitHub App

To create the GitHub App:
  1. In the upper-right corner of any page in GitHub, select your profile icon > Settings.

  2. In the left navigation, select Developer settings > GitHub Apps.

  3. Select New GitHub App.

  4. Complete the following fields as follows:

    • GitHub App Name: enter an appropriate name to reference this authentication, i.e. "Jenkins - <team name>".

    • Homepage URL: enter your company domain or GitHub repository URL.

    • Webhook URL: enter your Jenkins instance URL, i.e. https://<jenkins-host>/github-webhook/.

  5. You do not need to complete any of the fields in the Identifying and authorizing users section.

  6. Under Repository permissions, choose the following permissions. For each type of permission, use the drop-down menu to select Read-only, Read & write, or No access.

    • Administration: Read-only

    • Checks: Read & write

    • Contents: Read-only (to read the Jenkinsfile and the repository content during git fetch).

    • Metadata: Read-only

    • Pull requests: Read-only

    • (Optional)Webhooks: If you want the plugin to manage webhooks for you, Read & write.

    • Commit statuses: Read & write

      These permissions are the minimum permissions CloudBees Core will need for general Multibranch Pipeline workflows; however, you can add more permissions. We recommend that you select minimal permissions to limit the security risk if CloudBees Core is somehow compromised.
  7. Under Subscribe to events, select the following events:

    • Check run

    • Check suite

    • Pull request

    • Push

    • Repository

      If you do not see an event listed, check that you have applied the appropriate Repository permissions in the previous step. The events are added to the list based on the permissions selected.
      You can add additional events, the ones listed in this step are events CloudBees Core will use for general Multibranch Pipeline workflows.
  8. Select the appropriate choice for Where can this GitHub App be installed?

    • Only on this account: If you only want to use the GitHub App for a single GitHub account.

    • Any account: If you want to use the GitHub App for multiple organizations.

      If you select Any account, you will need one credentials entry in CloudBees Core per organization.
  9. Select Create GitHub App.

See Creating a GitHub App for more information on creating a GitHub App from GitHub’s Developer guide.
You are not required to use webhooks but it strongly recommended over alternatives such as polling. To use webhooks, add the Webhook URL and secret (noted above).
This version of CloudBees Core does not support concurrent registration of multiple webhook secrets.

Generating a private key for authenticating to the GitHub App

After you have created the GitHub App, you will need to generate a private key for authenticating to the GitHub App.

To generate a private key authenticating to the GitHub App:
  1. In the upper-right corner of any page in GitHub, select your profile icon > Settings.

  2. In the left navigation, select Developer settings > GitHub Apps.

  3. Select the GitHub App.

  4. Under Private keys, select Generate a private key option.

  5. A private key in PEM format will be downloaded to your computer.

Converting the private key for Jenkins

After you have generated the private key authenticating to the GitHub App, you need to convert the key into a different format that Jenkins can use with the following command:

openssl pkcs8 -topk8 -inform PEM -outform PEM -in key-in-your-downloads-folder.pem -out converted-github-app.pem -nocrypt

Installing the GitHub App to your organization

Finally, you must install the newly created app to your organization.

To install the newly created GitHub App to your organization:
  1. From the GitHub Apps settings page, select the GitHub App.

  2. In the left navigation, select Install App.

  3. Select Install next to the organization or user account containing the correct repository.

  4. Install the app on all repositories or select repositories.

  5. Once installed, you will have configuration options for the app on your selected account.

Adding the Jenkins credential

To add the Jenkins credential in the UI:
  1. From the CloudBees Core dashboard, select Credentials in the left navigation.

  2. Select the global credential store.

    cred store
  3. Select Add Credentials.

  4. Select GitHub App as the Kind.

  5. For the ID, enter the GitHub App Name you created in Creating the GitHub App.

  6. For App ID enter the GitHub App ID.

    The GitHub App ID can be found in the About section of your GitHub App under the General tab in GitHub.
    github apps settings
  7. (Optional) Enter the API Endpoint.

    This field will only appear if you are adding a Jenkins Credential to a GitHub Enterprise account.
  8. Select the Add button to enter the converted private key in the Key field.

  9. (Advanced) Select the Advanced…​ button if you have installed the same GitHub App on multiple organizations, and enter the name of the organization or user in the Owner field.

  10. Select OK.

Configuring the GitHub Organization

The following instructions assume you have already created a GitHub Organization in Jenkins. For more information on Creating projects based on GitHub repository structure.
To configure your GitHub Organization to use your GitHup App for authentication:
  1. From the GitHub Organization, select Configure in the left navigation.

  2. Select the Projects tab.

  3. Select the new GitHub App credentials from the Credentials drop down in the GitHub Organization section. GHApp verified, remaining rate limit: 5000 displays.

    If you are using GitHub Enterprise, the API URL must be set to your server. The API URL must be set on both the credential and the job.
  4. Select Save.

  5. In the left navigation, select Scan Organization Now.

  6. View the Scan Organization log and verify that the success message displays.

Configuring a master to use a webhook secret

  1. From the master, select Manage Jenkins > Configure System.

  2. Under GitHub > GitHub Servers, select the Advanced button next to a notebook with a pencil icon.

    advanced button
  3. For Shared secret, select Add and choose Jenkins.

    add cred button
  4. For Kind, select Secret text.

  5. Enter the webhook secret you added to the GitHub App in Creating the GitHub App.

  6. Select Add.