Getting Started

Want to manage access to your GitHub organization with ease? We have you covered. You can setup access management through Opal to GitHub in minutes.

Supported Services

  • GitHub organization repositories: Grant read, write, or admin access to any GitHub repository within your organization.

Notably, Opal does not yet support personal repositories.

Opal also does not yet support access management for GitHub accounts that are not members of your organization.

Setup

Create a GitHub connection

To get started, head to the Connections page and click on the GitHub Services tile to get started.

Click on the GitHub tile to get started.

Click on the GitHub tile to get started.

You will see a form with multiple steps that must be completed. Opal requires multiple credentials in order to manage your GitHub organization.

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 - Fill in details about your GitHub organization

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 - Sync every Opal user account with their GitHub account

This step must be completed for every single user that desires to use Opal to manage their GitHub organization repositories.

  1. In the top right, navigate to user settings and click on the gear.

Click on the

Click on the Settings gear.

2. Click Connect for the GitHub identity integration.

Click

Click Connect.

3. In the following form, for Organization name, enter the GitHub organization name you would like to synchronize via Opal, which must be a part of an existing Opal GitHub connection. For Username, enter your GitHub username, which must be a member of the GitHub organization. Critically, the GitHub account you wish to integrate must have a verified email address corresponding to your Opal email address. Otherwise, the integration will not succeed.

4. You will be redirected to a GitHub page, which will ask you to log into your GitHub account.

5. If successful, you will be redirected to the Opal user settings page, which should look like this (the status should say Connected and there should be a Disconnect button in place of Connect):

Your Opal account is now connected with your GitHub account.

Step 5 - Sync specific GitHub repositories with Opal

After creating the connection, the final step is to label repositories to sync with Opal. Opal achieves this via the Label feature in GitHub. Opal will only sync repositories with the opal label. The following steps describe how to mark repositories with this label:

1. In your repository, navigate to the Issues tab.

2. Click on the Labels tab in the top right.

3. Click New label in the top right.

4. Name the label opal and click Create label.

5. Your GitHub repository will now be synced with Opal.


❗️Enable Opal for access management

If you want to use Opal to manage access to GitHub resources, you will need to enable the Manage resources and groups from Opal in the Admin page. You can read more about how to do that here.


Did this answer your question?