Opal supports GitLab for all tiers (free, premium, and ultimate) for both GitLab Self-Managed and GitLab SaaS.

📘

GitLab Self-Managed vs. GitLab Saas

For GitLab Self-Managed, admins can import group AND personal repositories
For GitLab SaaS, admins can only import group repositories

Step 1 - Create a GitLab service account for Opal

GitLab SaaS

Under your top-level group that represents your organization on GitLab.com, create a new user with an Owner role. Please refer to GitLab instructions for this step. A new account is preferred because we will be using the personal OAuth access token corresponding to this account.

GitLab Self-Managed

Please log into your self-managed GitLab instance as an admin, and navigate to the Admin Area section, by clicking on Main menu > Admin Area > Users.

Afterward, proceed to create a new user and appoint the new user with the access level Administrator. This is shown in the screenshot below.

Step 2 - Create a GitLab OAuth app

Opal requires an Application to be set up on GitLab to handle projects and groups synchronization, as well as user pairing.

GitLab SaaS

Follow the instructions here to create a new OAuth App in your top-level GitLab group.

During the OAuth app creation process, for Name, you can enter Opal, or any other name you prefer.

For Redirect URL, please enter your domain name, followed by "/callback/gitlab/" (e.g., https://app.opal.dev/callback/gitlab/), and again, on a new line, your domain name, followed by "/callback/gitlab-connection/" (e.g., https://app.opal.dev/callback/gitlab-connection/).

🚧

Note: the backlashes at the end of these two Redirect URL are very important to GitLab, so don't forget them!

Set the app as Trusted and Confidential. Under Scopes, select api, profile, and email.

After creating your app, record the Application ID and copy the secret. These will be entered into the Application ID and Application Secret fields in Step 3.

GitLab Self-Managed

Follow the instructions here to create a new OAuth App in your GitLab Self-Managed instance.

During the OAuth app creation process, for "Name", you can enter "Opal" (or any other name you prefer). For "Redirect URI", enter your domain name, followed by "/callback/gitlab/" (e.g., https://app.opal.dev/callback/gitlab/), and again, on a new line, your domain name, followed by "/callback/gitlab-connection/" (e.g., https://app.opal.dev/callback/gitlab-connection/). Set the app as "Trusted" and "Confidential". Under "Scopes", select "api", "profile", and "email".

🚧

Note: the backlashes at the end of these two Redirect URL are very important to GitLab, so don't forget them!

After your app is created, record the Application ID and copy the secret. This will be entered into the Application ID and Application Secret fields in Step 3.

Step 3 - Create a new app in Opal and enter your GitLab settings into Opal

Head to the Catalog page, click on + App. Then, click on the GitLab tile.

If your GitLab instance is Self-Managed, click on Custom Domain and enter the domain of your instance.

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

If this step is successful, you will need to create a sync token.

Click on the Setup tab in the App overview page, and click on Connect OAuth Admin Token. This will redirect you to your Gitlab instance and you should use the GitLab account created in Step 1 to complete the OAuth flow.

Self-Managed

• Sync should start working automatically.

GitLab SaaS

• 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 (SaaS only) - Link GitLab identities to Opal accounts

To enable Opal to manage access to GitLab.com, each user must link their GitLab account to their Opal account.

Opal requires this step because GitLab only makes the email address of a GitLab account available via its API if a user has elected to publicly display their email address. Thus, Opal needs another way to match GitLab identities with Opal accounts. For security reasons, we ask users to log in to both Opal and GitLab to link their accounts.

Note: for the below steps, the GitLab 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 Connect next to the GitLab integration.

3. You will be redirected to a GitLab.com page, which will ask you to log into your GitLab account.