Skip to main content
Opal’s GitHub Enterprise connection lets you review and manage access to GitHub Enterprise teams and roles.
This page covers connecting a GitHub Enterprise Cloud (GHEC) enterprise account on github.com, including enterprise roles, enterprise teams, and multiple organizations in a single connection. If you only need to manage a single organization, follow the GitHub instructions instead. Opal does not currently support GitHub Enterprise Server (self-hosted) or GHE.com data-residency tenants.

​
Supported resources

When users request access to GitHub repositories, they can also request to assume specific roles.

​
Requirements

​
How to create an Admin Token (optional)

The Admin Token (a classic personal access token with the admin:enterprise scope, created by an enterprise owner) is optional. It is only used to sync and manage GitHub Enterprise teams and to import the Enterprise Owner role, because GitHub does not allow GitHub App tokens to call those endpoints. Leave it empty if you do not need either. We recommend not using your personal account to create this token.
  1. Log into the GitHub enterprise you want to integrate with Opal. Ensure the account you are creating a PAT for is an owner of the enterprise. Appoint the account you just created as co-owner of the enterprise.
  2. Create a personal access token for the owner account you just created. When creating the personal access token, enable the admin:enterprise permission. Take note of this for creating your GitHub Enterprise connection in Opal in Step 3.

​
1. Connect to GitHub Enterprise in Opal

To set up a new connection, go to Inventory > + App and select GitHub.
If you want to keep history of your old GitHub connection, you can migrate your existing connection to an enterprise connection. Simply go to Setup > Migrate to Enterprise Account in your existing connection, and continue following the steps below.
Fill in the App name, Enterprise Name, App admin and Description fields. Ensure that you have indicated this to be an enterprise account by checking the Is this an Enterprise account? checkbox below App name. If your organization uses SAML SSO, setting Enable SAML User Ingestion syncs users from your GitHub organization’s SAML SSO identities.
SAML SSO ingestion only includes users who have signed into GitHub at least once using your organization’s SAML SSO, in each organization where the Opal GitHub App is installed. Users provisioned in your IdP (e.g., Okta) who have never completed a GitHub SSO login will not appear in Opal until they do so.
After you select Continue, you’ll see a setup URL under Create GitHub App. Take note of this for the next step.

​
2. Create the GitHub App

You must be an owner of your GitHub enterprise to create the app and install it on the enterprise, an owner of each organization to install it there, and an Opal Admin to complete the connection in Opal.
For Opal to manage your GitHub enterprise’s resources, you must create a GitHub App within your enterprise. Create the app in your enterprise settings (Enterprise > Settings > GitHub Apps > New GitHub App), not in an organization or personal account, because Opal installs the app on your enterprise. Fill in the following fields: After creating the GitHub App, generate a Client secret and Private key.

​
3. Finish configuring Opal’s GitHub Enterprise connection

Back in Opal, fill in the Client ID, Client secret and Private key from your GitHub App. Optionally, in the Admin Token field, fill in the personal access token generated for your GitHub Enterprise owner account. See How to create an Admin Token if you need to create one. Then, select Create to create the GitHub Enterprise connection in Opal.

​
4. Install the GitHub App

After you select Create, you’ll be directed to GitHub to install the app you created in Step 2 on your enterprise. Installing the app on an organization at this step is not enough: the connection is not complete until the enterprise installation finishes. Then install the app in each organization you want to manage in Opal.
If the installation does not complete, delete the connection and start again.
Opal matches GitHub users to Opal accounts the same way for enterprise and organization connections: each user links their GitHub account in Account Settings > Identities, or you map GitHub usernames from your IdP. The GitHub account must have a verified email address that matches the user’s Opal email. Linked identities apply to every GitHub connection in Opal. See Link GitHub identities to Opal accounts for the steps.

​
Usage data and Risk Center

Opal can ingest usage data from your GitHub organizations to help identify usage patterns and surface unused access grants in the Risk Center. Usage data is collected from GitHub’s organization audit log (git clone, git fetch, and git push events). The Organization permissions → Administration: Read permission required for this is already included in the GitHub App setup in Step 2.

​
GitHub Repository Custom Roles

For organizations that have defined custom repository roles, these will appear in the roles tab for the organization resource. Upon first syncing a GitHub connection the 5 default repository roles will appear in this tab: Admin, Maintain, Write, Triage and Read. These 5 roles cannot be reordered relative to one another. Underneath these, “unreviewed” roles will appear. An admin can drag and drop these into the hierarchy around the default roles. This ordering will determine what repository role is pushed for a user that has multiple grants. Granting repository access with roles whose ordering has not been defined is unsupported. Custom repository roles can also be viewed in the roles tab for each individual repository. However, in this view their ordering is read-only. This is because repository roles are universal to all repositories in an organization and can thus only be changed from the organization resource’s roles tab.
Last modified on October 10, 2026