# GitLab

To allow users to log in with GitLab credentials, you’ll need to connect SonarQube to a GitLab OAuth 2 application. This will also allow you to configure users and groups.

## Creating a GitLab application for authentication and provisioning <a href="#creating-a-gitlab-oauth-app" id="creating-a-gitlab-oauth-app"></a>

1. First, you’ll need a GitLab OAuth 2 application. We recommend creating a dedicated application for authentication and provisioning, but if you’re already using one for pull request decoration (see [gitlab-integration](https://docs.sonarsource.com/sonarqube-server/10.5/devops-platform-integration/gitlab-integration "mention")), you can also use it for authentication and provisioning. See the [GitLab documentation](https://docs.gitlab.com/ee/integration/oauth_provider.html) for information on how to create the application.
2. Specify the following settings in your GitLab application:
   * **Name**: Your app’s name, such as SonarQube.
   * **Redirect URI**: \<Your SonarQube URL>/oauth2/callback/gitlab. For example, <https://sonarqube.mycompany.com/oauth2/callback/gitlab>.
   * **Scopes:** Select **api** if you plan to enable group synchronization. Select **read\_user** if you only plan to delegate authentication.
3. Save your application.

GitLab then takes you to the application’s page, where you can find your **Application ID** and **Secret**.

## Connecting your GitLab application to SonarQube <a href="#connecting-your-gitlab-application-to-sonarqube" id="connecting-your-gitlab-application-to-sonarqube"></a>

1. In SonarQube, Navigate to **Administration** > **Configuration** > **General Settings** > **Authentication** > **GitLab** and click **Create configuration**.
2. Fill the following fields with information from your GitLab application:
   * **Application ID**
   * **GitLab URL**: We recommend using [https://gitlab.com](https://www.google.com/url?q=https://gitlab.com\&sa=D\&source=docs\&ust=1702977557647128\&usg=AOvVaw1GxM3lkmuEM9OEG8xX3ha1). You can also use your own GitLab server URL.
   * **Secret**
3. **Synchronize user groups**: For each GitLab group they belong to, users will be assigned to a group with the same name (if it exists) in SonarQube.\
   On SonarQube, groups you want to synchronize must be named according to their GitLab URL:
   * `https://gitlab.com/my-gitlab-group` → `my-gitlab-group`
   * `https://gitlab.com/my-gitlab-group/sub-group` → `my-gitlab-group/sub-group`
4. Click **Save configuration**.

## Choosing the provisioning method <a href="#choosing-the-provisioning-method" id="choosing-the-provisioning-method"></a>

Once you’ve created your GitLab configuration, you can choose how users and groups are provisioned to SonarQube. For an overview of the available provisioning methods, see [overview](https://docs.sonarsource.com/sonarqube-server/10.5/instance-administration/authentication/overview "mention").

**Step 1**: In SonarQube, go to **Authentication** > **GitLab** and click **Enable configuration**.

**Step 2**: Select a provisioning method. The available options are:

* **Just-in-Time user and group provisioning (default)**:
  * The **Allow users to sign up** option allows new users to authenticate. When enabled, users are provisioned when they authenticate through Gitlab for the first time. When disabled, only existing users can authenticate to the server.
  * Use **Allowed groups** to restrict users allowed on SonarQube to certain GitLab groups. Only members of these groups (and sub-groups) will be allowed to authenticate. Enter the group slug as it appears in the GitLab URL, for instance, if the group URL is `https://gitlab.com/my-gitlab-group`, then enter `my-gitlab-group`.

{% hint style="warning" %}
If the allowed groups are not entered, any user with a GitLab account can log in to the SonarQube instance (assuming **Allow users to sign up** is set to true).
{% endhint %}

* * User information and group memberships are updated at each authentication.
* **Automatic user and group provisioning**:
  * Users and groups are synchronized on an hourly basis. The first synchronization happens immediately when you enable the feature.
  * The following information is required:
    * **Provisioning token**: GitLab token used for user provisioning. You can use either a group or a personal access token, as long as it has visibility on the desired groups. The token’s scope must include **read\_api**.
    * **Allowed groups**: ​​Only members of these groups (and sub-groups) will be provisioned. Enter the group slug as it appears in the GitLab URL, for example, "my-gitlab-group". Provisioning can only start from a group that has no parent, you can’t define a sub-group here.
  * You can check the status of the synchronization on this configuration page, in the **Automatic user and group provisioning** box.
  * If needed, you can manually trigger a synchronization by clicking **Synchronize now**.
  * Groups in SonarQube are named after the GitLab groups’ names, for example, *GroupA/GroupB.*
  * The user’s email address is only set when the user authenticates. Automatic synchronization won’t set or update emails.

**Step 3**: Click **Save**.

From the login page, your users can now log in to SonarQube using their GitLab accounts by clicking the **Log in with GitLab** button.