GitHub

Learn how to connect GitHub to Opal to manage access to your GitHub organization's repositories and teams.

📘

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.

1. Create an Opal app

To get started, go to the Inventory page and select the + App button on the top right. Then select the GitHub tile.

2. Create a GitHub organization owner account and owner personal access token

For Opal to manage your GitHub organization on your behalf, you need to create a GitHub owner account for your organization with proper permission scopes.

1. It's recommended you create a new GitHub account for this purpose by following GitHub's documentation. A fresh account is preferred because Opal needs to use 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. Next, appoint the account you just created as a co-owner of the organization.

3. Generate a personal access token for the owner account you just created. When creating the personal access token, enable the repo permission and leave everything else unchecked. Save this access token, which you will use for the Admin Token field in Step 4.

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

3. Create a GitHub organization OAuth app

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

Follow GitHub's documentation 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: you should not create a GitHub app.

Use the following fields during the OAuth app creation process:

After you create your app, record the Client ID and generate a new client secret. Save the generated client secret. These will be input into the Client ID and Client Secret fields in Step 4.

4. 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 2.

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

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

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.

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

📘

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 ask you to log into your GitHub account.