Authenticating with GitHub on Jenkins CI using a GitHub App

I spent over 90 hours figuring out which auth method works best. Save your time and check the right process here!

This guide is targeted to users who want to use a GitHub App to perform GitHub authenticated requests (such as cloning repos, pushing commits, opening PRs, listening to events, updating GitHub Checks, etc) from within Jenkins.

Why a GitHub App? Why not a shared bot account?

• 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 enforce 2FA to be enabled, with GitHub Apps there’s no need to manage 2FA tokens for (potentially multiple) bot accounts.

• To improve and tighten security: the Jenkins GitHub App that you will create requires a minimum, controlled set of privileges compared to a service user and its personal access token, which would require a much wider set of privileges.

• Access to GitHub Checks API: GitHub Apps can access the the GitHub Checks API to create check runs and check suites from Jenkins jobs and provide detailed feedback on commits as well as code annotation.

Why not an SSH key?

• It’d also require you to have a bot account with shared credentials across the team.

• Share the same limitations of username + password authentication explained above.

• From experience, Jenkins doesn’t play well with SSH keys, and plugins that work with it are quite buggy.

Why should I trust you?

I spent over 90 hours on trial-and-error process to figure out which authentication method works best, amongst username + password, personal access tokens, SSH keys, and GitHub App. If you’d like to figure out on your own all the reasons why to not use any other auth other than GitHub App, you’re in for a treat! 😉

Getting started

Before you get started make sure you have the required permissions:

GitHub

You'll need the permission to create a GitHub App.

If you're creating it on a personal account, then you can skip this requirement.

If you’re creating it in a organization, you need to be either the organization owner, or have been granted the permission to manage GitHub Apps.

Jenkins

You'll need the permission to create a new credential and update a job’s configuration. The specific permissions are:

• Credentials/Create

• Job/Configure

Creating the GitHub App

Follow the official GitHub guide for creating an app.

The only fields you need to fill out (currently) are:

• Github App name, e.g.: Jenkins - <team name>

• Homepage URL: your company’s website or a GitHub repository.

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

When setting up the required permissions for your GitHub App for a given repository, set the following permissions:

• Administration: read-only.

• Checks: read & write (so it can update the GitHub Checks in your pull requests).

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

• Metadata: read-only.

• Pull requests: read-only (or read & write if you intend to open pull requests using the bot at some point).

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

• Commit statuses: read & write.

Under “Subscribe to events”, subscribe to all events, and proceed to creating the GitHub App.

Authenticate to the GitHub App

After creating the GitHub App, you will need to generate a private key to authenticate to the GitHub App. Simply click in “Generate a Private Key” button.

Convert the private key for Jenkins

After you have generating and downloading the private key, you’ll need to convert it 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

Install the GitHub App to your organization

From the install app section of the newly created app, install the app to your organization. From here you can install the app on all repositories of your organization or in select repositories only. Once installed, you will have configuration options for the app on your selected account.

Add the Jenkins credential

You can add the Jenkins credential via the UI, or using the Jenkins Configuration as Code (a.k.a. JCasC) Plugin.

Via UI

• Navigate to the Add Credentials page in your Jenkins instance

• Fill out the form as follows:

  • Kind: GitHub App.

  • ID: give an identifiable name to this credential (you will use this in your Jenkinsfile to load this credential). Example: “<team_name>_github_app”.

  • App ID: the GitHub App ID, which can be found in the About section of your GitHub app, under the General tab.

  • API Endpoint (optional): only required for GitHub Enterprise.

  • Key: paste the contents of the converted private key from the previous section.

  • Owned (optional): if you've installed your same GitHub app on multiple organizations you’ll need to specify the name of the organization or user this app is going to be used on, e.g. “exampleorganization” for https://github.com/exampleorganization

• Click “Create”

Via Jenkins Configuration as Code (a.k.a. JCasC) Plugin

credentials:
  system:
    domainCredentials:
      - credentials:
        - gitHubApp:
            appID: "1111"
            description: "GitHub app"
            id: "github-app"
            # apiUri: https://my-custom-github-enterprise.com/api/v3 # optional only required for GitHub enterprise
            privateKey: "${GITHUB_APP_KEY}"

Conclusion

After following the steps in this tutorial, you should have a fully working GitHub App that can be used to access your repositories and perform actions on GitHub, such as cloning repos, pushing commits, creating PRs, listening to events, updating GitHub Checks in PRs, etc. In an upcoming tutorial I’ll cover how to use properly use this GitHub App credentials to set up the remaining of your Jenkins pipeline.