Before you start

You need a GitHub Enterprise account (cloud-hosted or self-hosted) with access to audit log GraphQL API. For more information, see GitHub's products. The GitHub integration polls events from the GraphQL API using a Personal Access Token.

Note: Our guide 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!

Step 1: Install the GitHub App

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

• Members: Read+Write
• Administration: Read-Only

Note: GitHub does not 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. 

Install the GitHub App

1. Navigate to the Expel GitHub Integration Application installation page: https://github.com/apps/expelgithubintegration and click Install.
   
   
2. Follow the steps to install the application within the GitHub Organization you want to onboard. Note: If you have multiple organizations, create a separate Security Device in Workbench for each organization.
3. After you have successfully installed the application, note the Installation ID that can be found in your URL under the format "github.com/.../installations/<installation_id>/…"

Step 2: Configure the technology in Workbench

Now that we have all the correct access configured and noted the credentials, we can integrate GitHub with Expel Workbench.  

Register device in Expel Workbench

1. In a new browser tab, login to https://workbench.expel.io/settings/security-devices?setupIntegration=github. 
   
2. For SIEM select Expel Cloud Service.
3. Complete all fields using the credentials and information you collected in Step 1. 
   • • For Name type the name of your GitHub organization.
     • For Location type Cloud.
     • For Organization name, type the name of your GitHub organization.
     • For Enterprise slug, type the enterprise slug URL (only required if you use an enterprise SAML identity provider, otherwise it can be left blank).
     • For the Application installation ID type the installation ID from Step 1.
4. Click Save. 
   

After a few minutes, refresh the Security Devices page and you see your device status reporting as Healthy, or if there is an issue, you see details of what the issue may be.

To check if alerts are coming through, navigate to Alerts on the console page. Click the icon in the upper right to switch to grid view, then check the list for device alerts.