GitHub Enterprise Server

Overview

Heeler connects to your GitHub Enterprise Server (GES) account by using a GitHub App that you create in your GES account. Your GitHub App will require information about Heeler (documented below) plus a Secret, which you will need to get from us directly. Please contact us via Slack or email for the Secret.

Requirements

• To connect to GitHub Enterprise Server, you must have permission to create a GitHub App. For Heeler to use the GitHub App, it must have the following permissions and subscribe to the following events:

  • Permissions:

    • Repository: Administration (read-only), Checks (read and write), Contents (read-only), Dependabot alerts (read-only), Dependabot secrets (read-only), Pull requests (read-only)

    • Organization: Members (read-only)

  • Events: Pull requests, Push, Release

• If your organization uses an IP Allow List, ensure that Heeler's outbound IP addresses are added for ports 443 and 22.

  • 44.221.229.40

  • 52.73.231.96

GitHub Enterprise Server Integration Information

1. In GHE, under your profile, navigate to Your organizations

1. Scroll down and click on Developer settings -> GitHub Apps

1. Then click on New GitHub App (the screenshot below also shows an existing GitHub App called Heeler Security)

1. Then fill in the details to register your GitHub App

   1. GitHub App name: A name appropriate for its purpose

   2. Write: Optional description of the App

   3. Homepage URL: https://app.heeler.com

   4. Callback URL: https://app.heeler.com/adminstration/connections/scm_accounts?type=GITHUB

   5. Expire user authorization tokens: Unchecked

1. GitHub App registration continued

   1. Webhook URL: https://gh-events.heeler.com/api/v1/github/payload

   2. Secret: Enter secret provided to you by Heeler

   3. SSL verification: Select Enable SSL verification

1. GitHub App registration continued

   1. Repository permissions:

      1. Administration: Read-only

      2. Checks: Read and write

      3. Contents: Read-only

      4. Dependabot alerts: Read-only

      5. Dependabot secrets: Read-only

      6. Pull requests: Read-only

1. GitHub App registration continued

   1. Organization permissions:

      1. Members: Read-only

1. GitHub App registration continued

   1. Subscribe to events

      1. Pull requests

      2. Push

      3. Release

1. GitHub App registration continued

   1. Where can this GitHub App be Installed?: Only on this account

   2. Select Create GitHub App

1. Copy the App ID value. This value is required when configuring the integration in Heeler Security. Specifically, you will need it when asked for the Application ID.

2. Click on the link to generate a private key. The link takes you to the next screenshot. (Alternatively, scroll down.)

1. Generate a private key

1. Confirm the creation of the private key and note the location of the downloaded pem file. The pem file's contents are required when configuring the integration in Heeler Security. Specifically, you will need the file contents when asked for the Private Key.

1. Scroll back up and click on Install App (N.b., another chance to copy down App ID value.)

1. Choose a GES account in which to install your newly registered GitHub App. In this screenshot, the chosen account is called Heeler and the newly registered GitHub App is called Heeler Security Docs. Click on the green Install button.

1. Select All repositories

2. Click on the green Install button.

1. Capture the URL to parse out the remaining required information when configuring the integration in Heeler Security. Specifically, the remaining required values are Installation ID, Organization, and Hostname.

2. The URL is of the format https://<Hostname>/organizations/<Organization>/settings/installations/<Installation ID>.

1. In this example, the URL is https://ghe.heeler.com/organizations/Heeler/settings/installations/3, so you would retrieve the following

   1. Installation ID: 3

   2. Organization: Heeler

   3. Hostname: ghe.heeler.com

Heeler Security Integration Information

1. Select the icon from the top navigation

2. Select Connections -> Code Organizations then select Add Code Organization -> GitHub Enterprise Server

1. Enter the required information in the modal

   1. Name: A name representing the GHE account

   2. Application ID: Enter the App ID obtained in an earlier step

   3. Installation ID: Enter the Installation ID obtained from parsing the captured URL

   4. Organization: Enter the Organization obtained from parsing the captured URL

   5. Hostname: Enter the Hostname obtained from parsing the captured URL

   6. Private Key: Enter the contents of the downloaded pem file created when generating a private key

2. Click Save

1. You should see confirmation that integration was successful with a Healthy status under Health