> ## 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 allows you to review and manage access to Github Enterprise teams and roles.
## Supported resources
| Resource | Read | Grant and revoke access |
| :----------------------------- | :--- | :---------------------- |
| 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
To set up your Github Enterprise connection in Opal:
* You must be an Opal Admin
* You must be a Github Enterprise Admin
* You must have a Github owner account for your enterprise
### How to create a Github owner account
We recommend **not** to use your personal account as Opal needs this personal
account token (PAT) to connect to your Github Enterprise.
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 app in Opal in [Step 3](#3-finish-connecting-github-enterprise-in-opal).
## Setup Instructions
### 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, Admin and Description fields respectively.
Ensure that you have indicated this to be an **Enterprise account** by checking the checkbox below App name. If your organization uses SAML SSO, you may Enable SAML SSO Ingestion to sync users from your Github organization's SAML SSO identities.
SAML SSO ingestion for Enterprise connections uses GitHub's SCIM API, which
automatically syncs all users provisioned in your IdP — no GitHub SSO sign-in
required from end users. To enable this, two things must be configured:
1. **On GitHub**: SAML SSO must be enabled on your organization, and a GitHub org owner must generate a Personal Access Token (classic) with the `admin:org` scope, authorized for SAML SSO. See [About SCIM for organizations](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations).
2. **On your IdP** (e.g., Okta): Configure the GitHub SCIM app using GitHub's SCIM endpoint (`https://api.github.com/scim/v2/organizations/{org}/`) and the PAT from step 1. See GitHub's [SCIM API reference](https://docs.github.com/en/enterprise-cloud@latest/rest/scim/scim?apiVersion=2022-11-28).
Without both configured, SCIM provisioning will not work.
Upon clicking continue, you will see a setup URL under **Create Github App**. Take note of this for the next step.
### 2. Create a Github App in Github Enterprise
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.
In Github Enterprise, go to Settings > Github Apps > New Github App. 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. In the Admin Token field, fill in the Personal Access Token generated for your Github Enterprise owner account. Refer [above](#how-to-create-a-github-owner-account) if you have not created one yet.
Then, click create to the Github Enterprise app in Opal.
### 4. Install Github app
Install the Github app you created in Step 2 for your enterprise by navigating to **Install App** and selecting your enterprise. You will also need to [install the app](https://docs.github.com/en/enterprise-cloud@latest/apps/using-github-apps/installing-your-own-github-app) in each organization you would like managed in Opal.