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 is 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:
Afterward, complete the following steps in Jenkins:
Supported versions
GitHub App authentication is available on the following versions and platforms:
CloudBees CI on modern cloud platforms version 2.222.4.3 (and higher)
CloudBees CI on traditional platforms version 2.222.4.3 (and higher)
GitHub Branch Source plugin version 2.7.1 (or higher)
Create the GitHub App
To create the GitHub App:
Do one of the following:
For a GitHub App owned by an organization: In the upper-right corner of any page in GitHub, selectyour profile icon > Your organizations then selectSettings for the organization.
For a GitHub App owned by a personal account: In the upper-right corner of any page in GitHub, selectyour profile icon > Settings.
In the left navigation, selectDeveloper settings > GitHub Apps.
SelectNew GitHub App.
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 such as
https://<jenkins-host>/github-webhook/.
You do not need to complete any of the fields in theIdentifying and authorizing users section.
UnderRepository permissions, choose the following permissions. For each type of permission, use the drop-down menu to selectRead-only, Read & write, orNo access.
Administration: Read-only
Checks: Read & write
Contents: Read-only (to read the
Jenkinsfileand the repository content duringgit fetch).Metadata: Read-only
Pull requests: Read-only
(Optional)Webhooks: If you want the plugin to manage webhooks for you, Read & write.
For more information on using webhooks with Jenkins, refer toCreating projects based on GitHub repository structure - Using build triggers and webhooks. Commit statuses: Read & write
These permissions are the minimum permissions CloudBees CI 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 CI is somehow compromised.
UnderSubscribe 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 CI will use for general Multibranch Pipeline workflows.
Select the appropriate choice forWhere 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 selectAny account, you will need one credentials entry in CloudBees CI per organization.
SelectCreate GitHub App.
| SeeCreating 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 CI does not support concurrent registration of multiple webhook secrets. |
Generate 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:
In the upper-right corner of any page in GitHub, selectyour profile icon > Settings.
In the left navigation, selectDeveloper settings > GitHub Apps.
Select the GitHub App.
UnderPrivate keys, selectGenerate a private key option.
A private key in PEM format will be downloaded to your computer.
Convert 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▼
Install 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:
From theGitHub Apps settings page, select the GitHub App.
In the left navigation, selectInstall App.
SelectInstall next to the organization or user account containing the correct repository.
Install the app on all repositories or select repositories.
Once installed, you will have configuration options for the app on your selected account.
Add the Jenkins credential
To add the Jenkins credential in the UI:
From the CloudBees CI dashboard, selectCredentials in the left navigation.
Select the global credential store.
SelectAdd Credentials.
SelectGitHub App as theKind.
For theID, enter the GitHub App Name you created inCreate the GitHub App.
ForApp ID enter the GitHubApp ID.
The GitHub App ID can be found in theAbout section of your GitHub App under theGeneral tab in GitHub. 
(Optional) Enter theAPI Endpoint.
This field will only appear if you are adding a Jenkins Credential to a GitHub Enterprise account. Select theAdd button to enter theconverted private key in theKey field.
(Advanced) Select theAdvanced… button if you have installed the same GitHub App on multiple organizations, and enter the name of the organization or user in theOwner field.
SelectOK.
Configure the GitHub Organization
| The following instructions assume you have already created a GitHub Organization in Jenkins. For more information seeCreate projects based on a GitHub repository structure. |
To configure your GitHub Organization to use your GitHup App for authentication:
From the GitHub Organization, selectConfigure in the left navigation.
Select theProjects tab.
Select the new GitHub App credentials from theCredentials drop down in theGitHub Organization section.
GHApp verified, remaining rate limit: 5000displays.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. SelectSave.
In the left navigation, selectScan Organization Now.
View theScan Organization log and verify that the success message displays.
Configure a controller to use a webhook secret
To configure a controller to use a webhook secret:
Select in the upper-right corner to navigate to theManage Jenkins page.
SelectSystem.
UnderGitHub GitHub Servers, selectAdvanced next to a notebook with a pencil icon.
For Shared secret, selectAdd and chooseJenkins.
For Kind, selectSecret text.
Enter the webhook secret you added to the GitHub App inCreate the GitHub App.
SelectAdd.
Unthrottle GitHub API usage
By default, CloudBees CI tries to be parsimonious with GitHub API usage since the rate limit can easily be exceeded when using a personal access token.Exceeding the rate limit is unlikely to be an issue when using a GitHub App for authentication, since the rate limit is elastic and much higher.
To unthrottle GitHub API usage:
Select in the upper-right corner to navigate to theManage Jenkins page.
SelectSystem.
Navigate toGitHub API usage Github API usage rate limiting strategy.
SwitchNormalize API requests toThrottle at/near rate limit, and then selectSave.Refer toGitHub rate limiting for more information.