# 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](https://docs.gitlab.com/). A connection to a GitLab Self-Managed instance is established and maintained through a GitLab OAuth application that you create on the instance. JetBrains Central Console 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 JetBrains Central Console 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 JetBrains Central Console. 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: 1. [Start the connection in JetBrains Central Console](#connect-gitlab-self-managed) to get the redirect URL and scopes. 2. [Create the application](#create-gitlab-app) on your GitLab Self-Managed instance. 3. [Provide the credentials in JetBrains Central Console](#provide-credentials) and [authorize the application](#authorize-app). > **Note:** > You can connect one GitLab OAuth application per GitLab Self-Managed instance. ### Create a connection Creating a connection means moving values in both directions: you start the connection in JetBrains Central Console to get the values that GitLab needs, create the application on your GitLab Self-Managed instance, and then bring its credentials back to JetBrains Central Console. Procedure: Start the connection in JetBrains Central Console 1. In the sidebar, under Integrations, select Hosted VCS. If you don't see this page, or the controls on this page are inactive, your role doesn't have the necessary [permissions](roles.html#permissions). 2. Click Connect VCS and select GitLab Self-Managed. A connection card appears on the page. 3. In the GitLab server URL field, specify the host of your GitLab Self-Managed instance. For example, `gitlab.jetbrains.com`. Procedure: Create the application in GitLab 1. Navigate to your GitLab Self-Managed instance and log in. 2. 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. > **Note:** > 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 JetBrains Central Console, create an instance-level application. > > * If you have multiple organizations in JetBrains Central Console and each organization corresponds to a single GitLab group, you can create a group-level application per group. 3. 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. JetBrains Central Console 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`. 4. 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. Procedure: Provide the credentials in JetBrains Central Console 1. Back in JetBrains Central Console, enter the following values: * Application ID: The ID of the GitLab application that you created. * Secret: The secret of the application that you created. ![Create a GitLab Self-Managed connection](images/gitlab-create-connection.png) 2. 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-app). ### 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. Procedure: 1. In the sidebar, under Integrations, select Hosted VCS. If you don't see this page, or the controls on this page are inactive, your role doesn't have the necessary [permissions](roles.html#permissions). 2. Click Authorize next to the connection you created, which has the Not connected status. ![List of Hosted VCS connections](images/gitlab-hosted-vcs-connection-list.png) You are redirected to your GitLab Self-Managed instance. 3. Click Authorize . You are redirected back to JetBrains Central Console. The connection status changes to Connected. > **Tip:** > If the connection fails, check that the server URL points to the instance itself rather than to a specific project, that the redirect URL in GitLab matches the one in the connection card exactly, and that the GitLab application has all of the required scopes. ## Manage connections Procedure: Edit a connection If the secret of the GitLab application is rotated, revoked, or otherwise changed in GitLab, provide the new secret in JetBrains Central Console to keep the connection working. 1. In the sidebar, under Integrations, select Hosted VCS. If you don't see this page, or the controls on this page are inactive, your role doesn't have the necessary [permissions](roles.html#permissions). 2. Click ![Ellipsis icon](images/union.svg) next to the connection you want to edit and select Edit connection. 3. Update as needed: * Secret: The new secret for the GitLab application. > **Note:** > 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](#remove-gitlab-connection) and create a new one. 4. Click Save. You have updated the connection details. Procedure: Remove a connection > **Warning:** > Removing a connection revokes access to the repositories of the connected instance for everyone in your organization. The GitLab application itself is not deleted from your GitLab Self-Managed instance, so delete it in GitLab as well if you no longer need it. 1. In the sidebar, under Integrations, select Hosted VCS. If you don't see this page, or the controls on this page are inactive, your role doesn't have the necessary [permissions](roles.html#permissions). 2. Click ![Ellipsis icon](images/union.svg) next to the connection you want to remove and select Remove connection. 3. Click Remove to confirm the action. The connection card is removed from the page.