Jenkins GitHub OAuth Plugin (GitHub Authentication plugin)

Why: Use GitHub user credentials to administer Jenkins instance, using GitHub OAuth Application.

Plug-in details: https://plugins.jenkins.io/github-oauth

Configuration (Github): Step1: https://github.com → Settings → Developer Settings → New OAuth Apps → New OAuth App.

• Application Name: Jenkins
• HomePageURL: Your Jenkins landing page URL, for me it is https://jenkis..ninja
• Application Description: Whatever you like
• Authorization callback: <JENKINS_URL>:<JENKINS_PORT>/securityRealm/finishLogin please make sure your spellings are correct

Add your application

Step 2: Configuration (Jenkins)

• Enable security checkbox
• Access Control checkbox
• Github Authentication plugin
• Github Web URI: https://github.com or your own Github server instance
• Client Id: which will you get from Github
• Client Secret: Secret key that you will get from GitHub while Adding Jenkins as application
• OAuth Scope(s): read:org,user:email,repo

Then Authorization:

• Matrix-based Security: checkbox check as checked-in screenshot

For more details please read https://plugins.jenkins.io/github-oauth/

Check first if you have the github-oauth Jenkins plugin installed, as described in "Use the Jenkins OAuth plug-in to securely pull from GitHub", from Walker Rowe.

That would allow to register your Jenkins server as an application which can then access GitHub resources:

You can accomplish this by using a GitHub App and its "client secret." To do this, you need to have admin rights in the GitHub Organization.

1. Go to the GitHub Organization settings - URL is like https://github.com/organizations/MyOrganization/settings/apps

2. Click the button to create a New GitHub App.

3. Fill out the required data for the app Name and URL (I just used the Organization page URL).

4. Un-check the Webhook > Active option.

5. In the Repository Permissions section, I selected the following:

   1. Actions: Read & Write

   2. Commit Status: Read & Write

   3. Contents: Read-only

   4. Packages: Read & Write (some of our jobs publish artifacts to GitHub Packages, yours may not need this).

   5. Pull Requests: Read-only

6. Click the button to Create GitHub App.

7. Back on the App page, click the button to Generate a new client secret.

   1. Copy the generated secret NOW, it won't be visible later.

8. Also take note of the App ID (as of now, a 7-digit number).

9. Click the Install App link (left-side navigation), then install the app into your Organization account.

Back in Jenkins...

Now that you have the App ID and Client Secret, go to your Jenkins server and navigate to the Credentials page (Manage Jenkins > Credentials).

1. Click the Scope and Domain (System by default) and Domain ("global" by default) for the new credential, then Add Credentials.

2. On the New Credentials form, select GitHub App as the Kind.

3. For ID, leave it blank or make one up. This is NOT the GitHub App ID, this is the Jenkins credential ID and it will be generated if you don't enter one.

4. For App ID, enter the App ID you noted in step 8 above.

5. For Key, you'll use the client secret you copied in step 7.1 above.

   1. Make sure to click the help link (? icon) next to the Key label to get instructions for converting the secret into the right format.

6. Click the Test Connection button to make sure you copy/pasted everything correctly.

7. Click the Create button to add this credential.

This credential can now be selected for use in the Source Code Management of your Jenkins builds.

If you're using the Branch Source Plugin with GitHub App authentication, you don't have a token at hand in Jenkins. But the credentials provider is smart enough to give you an access token derived from the App with just the same withCredentials step:

withCredentials([usernamePassword(credentialsId: 'id-of-your-github-app-credentials',
                                  usernameVariable: 'GITHUB_APP',
                                  passwordVariable: 'GITHUB_ACCESS_TOKEN')]) {
  // Use the access token via $GITHUB_ACCESS_TOKEN here
}

Note that you have to use usernamePassword as type, even if your credentials referenced by ID are of type GitHub App.

See official Jenkins blog post n GitHub App authentication for further info.