You must have:


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


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.

    • 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

  1. In a new browser tab, login to

  2. For Where is your device? select:

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

    2. 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 Cloud.

    • 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.

  5. For Application Private PEM, base64 encode your PEM, and then paste it in this field. The PEM must be base64-encoded.


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!