> ## 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
> Connect Opal to your GitHub organization to manage and review access.
Learn how to connect GitHub to Opal to manage access to your GitHub organization's repositories and teams.
## Supported resources
Opal does not yet support personal repositories. Opal also does not yet
support access management for GitHub users that are not members of your
organization.
| Resource | Read | Grant and revoke access | Available in Risk Center |
| - | - | - | - |
| GitHub teams | ✔️ | ✔️ | ✔️ |
| GitHub repositories | ✔️ | ✔️ | ✔️ |
| GitHub organization roles | ✔️ | ✔️ | ✔️ |
| GitHub organization owner role | ✔️ | ✔️ | ✔️ |
When users request access to GitHub repositories, they can also request to assume specific roles.
## 1. Create an Opal app
To set up a new connection, go to the **Inventory** page and select the **+ App** button on the top right. Then select the GitHub tile.
To upgrade an existing Opal app, go to the **Setup** tab in the **Inventory** and select **Register App**.
## 2. Create the GitHub App
Ensure you have permissions to create a GitHub App in your GitHub
organization.
If you're creating the app for the first time, enter an app name, GitHub organization name, app admin, and description.
If your organization uses SAML SSO, setting **Enable SAML SSO 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. 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. If you need all IdP users synced automatically without
requiring a GitHub SSO sign-in, consider setting up a{" "}
GitHub Enterprise connection{" "}
with SCIM provisioning configured in your IdP.
After you create the Opal app or select **Register App** for an existing integration, you'll be directed to GitHub to create the [GitHub App](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps).
## 3. Optional: Link GitHub identities to Opal accounts
GitHub only makes the email address of a GitHub account available via its API if a user has elected to publicly display their email address. Thus, Opal needs another way to match GitHub identities with Opal accounts.
If your organization does not use SAML SSO, each user must link their GitHub account to their Opal account. If you've enabled SAML SSO ingestion, users can still manually link GitHub identities, but SAML usernames will take precedence.
For security reasons, we ask users to log in to both Opal and GitHub to link their accounts.
For the following steps, the GitHub account you wish to integrate **must have
a verified email address corresponding to your Opal email address**.
1. In the bottom left, click your **User** > **Account Settings**.
2. Click **Identities** > **Connect** next to the GitHub integration.
3. You will be redirected to a GitHub page, which will prompt you to log into your GitHub account.
### Programmatically map GitHub usernames
If your end users cannot manually link accounts—e.g., if you're connecting service accounts to Opal—you can alternatively set the GitHub username as an attribute in your IdP and [import it as a user attribute]().
## Usage data and Risk Center
Opal can ingest usage data from your GitHub organization to help identify usage patterns and surface unused access grants in the [Risk Center](/docs/least-privilege-posture-management).
Usage data is collected from GitHub's organization audit log (`git clone`, `git fetch`, and `git push` events). This requires your organization to be on **GitHub Enterprise Cloud** and the Opal GitHub App to have **Organization permissions → Administration: Read**. The **Register App** flow requests this permission automatically. If your organization is not on GitHub Enterprise Cloud, Opal skips audit log collection — other sync functionality is unaffected.
## Github Organization Owner Support
To leverage Github Organization Owner Support in your Opal environment, go to your **Github App** > import the **Github Organization** resource. The member / admin (owner) roles will be automatically populated and show up as access levels on the Organization in the request modal.
## 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 respository. 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.