GitLab Self-Managed

GitLab Self-Managed is a GitLab deployment that your organization installs and runs on its own infrastructure. For more information, see the GitLab documentation.

A connection to a GitLab Self-Managed instance is established and maintained through a GitLab OAuth application that you create on the instance. Air Governance shows the redirect URL and the scopes that the application requires, and you provide the application ID and secret in return. Access is delegated per user: each user authorizes the application with their own GitLab account, so in JetBrains Air and other services based on Air Governance they see only the projects that their GitLab permissions allow.

Prerequisites

Before you start, make sure that:

Your GitLab Self-Managed instance is reachable from Air Governance. Instances that are only available inside a private network cannot be connected.
You have permission to create a GitLab OAuth application. Alternatively, you can ask a GitLab administrator to create one for you and provide its details.

Connect a GitLab Self-Managed instance

The process of connecting a GitLab Self-Managed instance consists of the following steps:

Start the connection in Air Governance to get the redirect URL and scopes.
Create the application on your GitLab Self-Managed instance.
Provide the credentials in Air Governance and authorize the application.

Create a connection

Creating a connection means moving values in both directions: you start the connection in Air Governance to get the values that GitLab needs, create the application on your GitLab Self-Managed instance, and then bring its credentials back to Air Governance.

Start the connection in Air Governance

In the sidebar, under Integrations, select Hosted VCS.
If you don't see this page, or the controls on this page are inactive, make sure your role has the necessary permissions permissions.
Click Connect VCS and select GitLab Self-Managed.
A connection card appears on the page.
In the GitLab server URL field, specify the host of your GitLab Self-Managed instance. For example, gitlab.jetbrains.com.

Create the application in GitLab

Navigate to your GitLab Self-Managed instance and log in.
Open the applications page:
- For group-level applications, navigate to your group, then select Settings | Applications | Add new application.
- For instance-level applications, navigate to Admin | Applications | New application. This requires administrator access to your GitLab Self-Managed instance.
A group-level application provides access only to the group in which it was created. Choose the application type based on how your organizations map to GitLab groups:
- If you need access to multiple GitLab groups from a single organization in Air Governance, create an instance-level application.
- If you have multiple organizations in Air Governance and each organization corresponds to a single GitLab group, you can create a group-level application per group.
Enter the following details:
- Redirect URI: The redirect URL shown in the connection card:
  https://api.jetbrains.cloud/repo-connections/auth/callback
  To copy it, click the copy icon next to the value.
- Confidential: Select this checkbox. Air Governance stores the application secret.
- Trusted (Applies only to instance-level applications): Mark the application as trusted. The user authorization step is automatically skipped for the application.
- Scopes: api, read_user, read_repository, and write_repository.
Save the application in GitLab and copy the generated application ID and secret. GitLab shows the secret only once, so copy it before you leave the page.

Provide the credentials in Air Governance

Back in Air Governance, enter the following values:
- Application ID: The ID of the GitLab application that you created.
- Secret: The secret of the application that you created.
Click Connect.
The connection is created, but its status is Not connected. To establish a working connection, follow the instructions to authorize the GitLab application.

Authorize the GitLab application

Authorization is the final step of the connection process. You authorize the application once to finalize the connection for your organization. Each user then authorizes the application with their own GitLab account the first time they use the connection, so everyone sees only the projects that their GitLab permissions allow. For an instance-level application, individual user authorization won't be needed if Trusted was selected during creation of the application.

In the sidebar, under Integrations, select Hosted VCS.
If you don't see this page, or the controls on this page are inactive, make sure your role has the necessary permissions permissions.
Click Authorize next to the connection you created, which has the Not connected status.
You are redirected to your GitLab Self-Managed instance.
Click Authorize <application-name>.
You are redirected back to Air Governance. The connection status changes to Connected.

Manage connections

Edit a connection

If the secret of the GitLab application is rotated, revoked, or otherwise changed in GitLab, provide the new secret in Air Governance to keep the connection working.

In the sidebar, under Integrations, select Hosted VCS.
If you don't see this page, or the controls on this page are inactive, make sure your role has the necessary permissions permissions.
Click next to the connection you want to edit and select Edit connection.
Update as needed:
- Secret: The new secret for the GitLab application.
The GitLab server URL and Application ID values are read-only. To connect a different GitLab Self-Managed instance or use a different GitLab application, remove the connection and create a new one.
Click Save.
You have updated the connection details.

Remove a connection

In the sidebar, under Integrations, select Hosted VCS.
If you don't see this page, or the controls on this page are inactive, make sure your role has the necessary permissions permissions.
Click next to the connection you want to remove and select Remove connection.
Click Remove to confirm the action.
The connection card is removed from the page.

06 October 2026