This article explains how to connect GitHub to Workbench.

You must have:

  • A GitHub Enterprise account license. For more information, see GitHub products.

Note

This procedure is specifically for self-hosted GitHub deployments. For cloud-hosted, use the GitHub cloud-hosted Workbench setup guide.

Step 1: Install the self-hosted GitHub App

Workbench uses a GitHub App as part of the onboarding process. During installation, the Expel GitHub App receives the following organization-level privileges:

  • Members: Read+Write

  • Administration: Read-only

Note

GitHub doesn't log user identities, making it difficult to track suspicious activity at the user level. To solve this problem, Expel uses Write Permissions to map GitHub data to a user's identity.

  1. Use the Create a GitHub App instructions to create a custom application in the organization you want monitored. Fill in the required fields like this:

  2. Navigate to the organization's Apps Settings page. Example URL: https://github.*****/organizations/*****/settings/apps/ExpelGitHubIntegration.

  3. Write down the App ID.

  4. Use the Authenticating with GitHub Apps instructions to generate a private key and store it for later use. This is your PEM key and you need it in the next section.

    Note

    If you have multiple organizations, create a separate Security Device in Workbench for each organization.

  5. If you are using an Expel Assembler within your network, use the Managing allowed IP addresses for a GitHub App instructions to add the assembler's internal IP to the allow list. Otherwise, add the Expel egress IPs to the allow list:

Step 2: Configure the technology in Workbench

Note

Expel secures all login information our SOC analysts need about your devices in a MFA password product. Access to this login information is protected using our internal MFA processes. To learn more about the IP addresses all Expel traffic comes from, go here.

  1. In a new browser tab, log into https://workbench.expel.io/settings/security-devices?setupIntegration=github.

    Github_Device_Connect_on_prem.png
  2. For Where is your device? select:

    • If you decided to allowlist the Expel egress IPs, select Cloud.

    • If you are using an Assembler, select On-prem.

  3. For Assembler select the Assembler from the list. N/A for Cloud.

  4. Complete these fields using the credentials and information from Step 1.

    • For Name, type the name of your GitHub organization.

    • For Location, type On-prem.

      Tip

      If you are onboarding more on-prem devices, type a name that indicates what each device is tracking.

    • For Organization name, type the name of your GitHub organization.

    • For Enterprise slug, type the Enterprise name.

    • For the Application installation ID, type the installation ID from Step 1.

    • For Application ID, type the application ID from Step 1.

    • For Application Private PEM, copy and paste the PEM file contents from Step 1.

Tip

This article was accurate at the time of writing, but changes happen. If you find the instructions are outdated, leave a description in the comment field below and let us know!