This procedure is specifically for self-hosted GitHub deployments. For cloud-hosted, refer to GitHub Cloud Setup for Workbench.
This article explains how to connect GitHub Self-Hosted (on-prem) to Workbench.
Prerequisites
You must have:
-
A GitHub Enterprise account license. For more information, see GitHub products.
Quick Links
Step 1: Install the Self-Hosted GitHub App
Workbench uses a GitHub App as part of the onboarding process.
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.
-
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:
-
GitHub App name: ExpelGitHubIntegration
- Homepage URL: https://github.com/apps/expelgithubintegration
- Webhook: uncheck Active.
-
Organization permissions:
-
Members: Read+Write
-
Administration: Read-Only
-
-
Leave all other fields blank.
-
-
Navigate to the organization's Apps Settings page. Under the About section, copy the value of App ID for use later in this process.
-
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. - 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 IPs to the allow list. Refer to Connecting Your Devices to Workbench Securely for a list of Expel egress IPs.
Step 2: Configure the Technology in Workbench
Now that we have the correct access configured and noted the credentials, we can integrate your tech with Workbench.
-
In a new browser tab, log into https://workbench.expel.io/settings/security-devices?setupIntegration=github.
-
For Where is your device?:
-
If you decided to allow the Expel egress IPs, select Cloud.
-
If you are using an Assembler, select On-prem.
-
-
For Assembler, select the Assembler from the list or N/A for Cloud.
-
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.
Note
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.
-
- Click Save.
You can see if the device is healthy on the Security Devices page. It may take a few minutes to see the device listed as healthy.
To check if alerts are coming through, navigate to the Alerts Analysis page. Scroll to the device you want to check and click View alerts. Switch to grid view, then check the list for device alerts. It can take 36 to 72 hours for alerts to appear after setup as we tune your device.