Want to manage access to your GitHub organization's repos and teams? We have you covered. You can setup Opal to manage access to GitHub in minutes.

Note: 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.

Getting Started

To get started, head to the Catalog page, click the + App button on the top right. Then, click on the GitHub tile.

Step 1 - Create a GitHub organization owner account and owner personal access token

In order for Opal to manage your GitHub organization on your behalf, we'll need you to create a GitHub owner account for your organization with proper permission scopes.

1. We suggest creating a fresh GitHub account for this purpose (follow the instructions here). A fresh account is preferred because we will be using the personal access token corresponding to this account.

2. Log into the GitHub organization you want to integrate with Opal. You should be an owner of that organization. Then appoint the account you just created as a co-owner of the organization (see instructions here).

3. Generate a personal access token for the owner account you just created, following instructions from this link. When creating the personal access token, the "repo" permission should be checked off, with everything else unchecked. Record this access token, which will be input into the "Admin Token" field later on in Step 3.

Note that Opal will use this personal access token, and since only the "repo" permission was checked, Opal will not be able to delete repositories in your organization.

Step 2 - Create a GitHub organization OAuth app

Opal requires an OAuth app in your GitHub organization for matching GitHub accounts with Opal user accounts.

Follow the instructions here to create an OAuth app for your GitHub organization. Note that this is an OAuth app, not a GitHub app. It is easy to confuse the two---we do not want to create a GitHub app.

During the OAuth app creation process, for "Application Name", you can enter "Opal" or any other name you prefer. For "Homepage URL", enter the domain name for your Opal instance. For "Authorization callback URL", enter your domain name, followed by "/callback/github" (e.g., https://app.opal.dev/callback/github).

After your app is created, record the Client ID and generate a new client secret. Record the generated client secret. These will be input into the "Client ID" and "Client Secret" fields in Step 3.

Step 3 - Enter your GitHub organization's credentials into Opal

For Organization Name, you must input your actual GitHub organization name.

For Admin Token, use the personal access token from Step 1.

For Client ID and Client Secret, use the generated credentials from Step 2.

If this step is successful, you have completed setting up the GitHub organization connection information required as the GitHub organization owner!

However, to complete the entire process and permit access management to your repositories via Opal, the next step must be completed for every single Opal user in your organization.

Step 4 - Link GitHub identities to Opal accounts

To use Opal to manage access to GitHub, each user must link their GitHub account to their Opal account.

Opal requires this step because 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. For security reasons, we ask users to log in to both Opal and GitHub to link their accounts.

Note: for the below 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 ask you to log into your GitHub account.