Skip to content

Latest commit

 

History

History
141 lines (96 loc) · 4.69 KB

github-app.adoc

File metadata and controls

141 lines (96 loc) · 4.69 KB
Raw

GitHub app authentication guide

This guide is targeted to users who want to use a GitHub app to authenticate to Jenkins.

Why?

  • the rate limit for a GitHub app scales with your organization size, whereas a user based token has a limit of 5000 regardless of how many repositories you have,

  • for organization’s that have 2fa enforced - no need to manage 2fa tokens for a 'bot' user

  • to improve and tighten security: the Jenkins GitHub app requires a minimum, controlled set of privileges compared to a service user and its personal access token which has a much wider set of privileges

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 section, otherwise:

  • organization owner

or

Jenkins

You’ll need the permission to create a new credential and update job configuration, the specific permissions are:

  • Credentials/Create

  • Job/Configure

Creating the GitHub app

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

Permissions this plugin uses:

  • Commit statuses - Read and Write

  • Contents: Read-only (to read the Jenkinsfile and the repository content during git fetch). You may need "Read & write" to update the repository such as tagging releases

  • Metadata: Read-only

  • Pull requests: Read-only

Under Subscribe to events, enable all events.

Click 'Create GitHub app'

You now need to generate a private key authenticating to the GitHub app

Click the 'generate a private key' option.

After a couple of seconds the key will be downloaded to your downloads folder.

Now you need to convert the key into a different format that Jenkins can use:

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

Install the GitHub app

  • From the install app section of newly created app, install the app to your organization.

Adding the Jenkins credential

UI

  • From the Jenkins main page click 'Credentials'

  • Pick your credential store, normally (global)

  • Click 'Add credentials'

Fill out the form:

  • Kind: GitHub app

  • ID: i.e. github-app-<team-name>

  • App ID: the github app ID, it can be found in the 'About' section of your GitHub app in the general tab.

  • API endpoint (optional, only required for GitHub enterprise this will only show up if a GitHub enterprise server is configured).

  • Key: click add, paste the contents of the converted private key

  • Advanced: (optional) If you’ve installed your same GitHub app on multiple organizations you need the next step

  • Click OK

Configuration as Code 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}"

Configuring the github organization folder

See the main documentation for how to create a GitHub folder.

  • Load the folders configuration page

  • Select the GitHub app credentials in the 'Credentials field drop down

  • If you are using GitHub enterprise make sure the API url is set to your server, (note you currently need to set the API url on both the credential and the job).

After selecting the credential you should see:

GHApp verified, remaining rate limit: 5000

  • Click save

  • Click 'Scan organization now'

  • Click 'Scan organisation log'

Verify at the bottom of the scan log it says:

Finished: SUCCESS

Help?

Raise an issue on Jenkins jira setting the 'component' to be github-branch-source-plugin