> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Enterprise

> Connect Opal to your GitHub Enterprise account to manage and review access.

Opal's GitHub Enterprise connection lets you review and manage access to GitHub Enterprise teams and roles.

> [!NOTE]
>
> 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](https://docs.opal.dev/integrations/github.md) instructions instead. Opal does not currently support GitHub Enterprise Server (self-hosted) or GHE.com data-residency tenants.

## Supported resources

| Resource | Read | Grant and revoke access |
| :- | :- | :- |
| GitHub repositories | ✔️ | ✔️ |
| GitHub teams | ✔️ | ✔️ |
| GitHub Enterprise teams | ✔️ | ✔️ |
| GitHub organization roles | ✔️ | ✔️ |
| GitHub Enterprise roles | ✔️ | ✔️ |
| GitHub organization owner role | ✔️ | ✔️ |
| GitHub organization | ✔️ | |

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

## Requirements

### How to create an Admin Token (optional)

> [!NOTE]
>
> 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](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) 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](#3-finish-configuring-opals-github-enterprise-connection).

## 1. Connect to GitHub Enterprise in Opal

To set up a new connection, go to **Inventory > + App** and select **GitHub**.

> [!NOTE]
>
> 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.

> [!WARNING]
>
> 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

> [!NOTE]
>
> 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](https://docs.github.com/en/enterprise-cloud@latest/apps/creating-github-apps/registering-a-github-app/registering-a-github-app#registering-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:

| Field | Input |
| :- | :- |
| GitHub App Name | A descriptive name |
| Homepage URL | Your homepage URL |
| Callback URL | [https://app.opal.dev/callback/github](https://app.opal.dev/callback/github) |
| Setup URL | The setup URL you took note of in Step 1 |
| Webhook | Inactive |
| Repository Permissions | Administration: Read and Write |
| Organization Permissions | Administration: Read and Write Members: Read and Write |
| Account Permissions | Email addresses: Read only |
| Enterprise Permissions | Custom Enterprise Roles: Read and Write Enterprise Organizations: Read and Write Enterprise People: Read only Enterprise Teams: Read and Write Enterprise Organization Installations: Read only |

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](#how-to-create-an-admin-token-optional) 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](https://docs.github.com/en/enterprise-cloud@latest/apps/using-github-apps/installing-your-own-github-app) in each organization you want to manage in Opal.

> [!NOTE]
>
> If the installation does not complete, delete the connection and start again.

## 5. Optional: Link GitHub identities to Opal accounts

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](https://docs.opal.dev/integrations/github.md#3-optional-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](https://docs.opal.dev/docs/least-privilege-posture-management.md).

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](#2-create-the-github-app).

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.