# GitLab integration

SonarQube’s integration with GitLab self-managed and GitLab SaaS subscriptions allows you to maintain code quality and security in your GitLab projects.

With this integration, you’ll be able to:

* **Authenticate with GitLab**: Sign in to SonarQube with your GitLab credentials.
* **Import your GitLab projects**: Import your GitLab Projects into SonarQube to easily set up SonarQube projects.
* **Analyze projects with GitLab CI/CD**: Integrate analysis into your build pipeline. Starting in [Developer Edition](https://www.sonarsource.com/plans-and-pricing/developer/), SonarScanners running in GitLab CI/CD jobs can automatically detect branches or merge requests being built so you don’t need to specifically pass them as parameters to the scanner.
* **Report your quality gate status to your merge requests**: (starting in [Developer Edition](https://www.sonarsource.com/plans-and-pricing/developer/)) See your [quality-gates](https://docs.sonarsource.com/sonarqube-server/10.5/user-guide/quality-gates "mention") and code metric results right in GitLab so you know if it’s safe to merge your changes.

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* To integrate SonarQube with GitLab self-managed subscriptions, we recommend using [GitLab version 15.6+](https://about.gitlab.com/releases/2022/11/22/gitlab-15-6-released/).
* You’ve set a SonarQube **Server base URL** in **Administration** > **Configuration** > **General Settings > General**.

#### Branch analysis <a href="#branch-analysis" id="branch-analysis"></a>

Community Edition doesn’t support the analysis of multiple branches, so you can only analyze your main branch. Starting in [Developer Edition](https://www.sonarsource.com/plans-and-pricing/developer/), you can analyze multiple branches and merge requests.

### Authenticating with GitLab <a href="#authenticating-with-gitlab" id="authenticating-with-gitlab"></a>

See [gitlab](https://docs.sonarsource.com/sonarqube-server/10.5/instance-administration/authentication/gitlab "mention") for more details on your authentication settings in GitLab.&#x20;

### Importing your GitLab projects into SonarQube <a href="#importing-your-gitlab-projects-into-sonarqube" id="importing-your-gitlab-projects-into-sonarqube"></a>

If you import your GitLab projects into SonarQube then the corresponding SonarQube projects will be automatically created and set up:

* The project’s main branch name will be automatically set up from GitLab.
* From the [Developer Edition](https://www.sonarsource.com/plans-and-pricing/developer/): the report of the quality gate to the merge requests will be automatically set up on the SonarQube projects.

#### Setting up the import of GitLab projects <a href="#setting-up-the-import-of-gitlab-projects" id="setting-up-the-import-of-gitlab-projects"></a>

You need the Administration System permission to be able to set up the import of GitLab projects into SonarQube.

To set up the import of GitLab projects into SonarQube:

1. Go to **Administration > Configuration > General Settings > DevOps Platform Integrations**.&#x20;
2. Select the **GitLab** tab and click **Create configuration**. The **Create a configuration** dialog opens.
3. Specify the following settings:
   * **Configuration Name** (Enterprise and Data Center Edition only): The name used to identify your GitLab configuration at the project level. Use something succinct and easily recognizable.
   * **GitLab URL**: The GitLab API URL. We recommend using <https://gitlab.com>. You can also use your own GitLab server URL.
   * **Personal Access Token**: Token used to connect to the GitLab user account used to report the quality gate status to merge requests. See below.
4. Click **Save configuration**.

#### Providing a GitLab personal access token <a href="#providing-a-gitlab-personal-access-token" id="providing-a-gitlab-personal-access-token"></a>

You must provide a personal access token of the GitLab user account used to report the quality gate to the merge requests. This token will be stored in SonarQube and can be revoked at any time in GitLab.

We recommend using a dedicated GitLab account with at least Reporter [permissions](https://docs.gitlab.com/ee/user/permissions.html) (the account needs permission to leave comments). Use a personal access token from this account with the `api` scope authorized for the repositories you’re analyzing.

If you want to enter the token in SonarQube in encrypted format: Administrators can encrypt this token at **Administration** > **Configuration** > **Encryption**. See the **Settings Encryption** section of the [security](https://docs.sonarsource.com/sonarqube-server/10.5/instance-administration/security "mention") page for more information.

### Analyzing projects with GitLab CI/CD <a href="#analyzing-projects-with-gitlab-ci-cd" id="analyzing-projects-with-gitlab-ci-cd"></a>

SonarScanners running in GitLab CI/CD jobs can automatically detect branches or merge requests being built so you don’t need to specifically pass them as parameters to the scanner.

The in-product tutorial will give you all the necessary information to analyze your project.

To analyze your projects with GitLab CI/CD, you need to:

* Set your environment variables.
* Configure your .gitlab-ci.yml file.

The following sections detail these steps.

{% hint style="warning" %}
The errors "*Missing blame information…*" and "*Could not find ref…*" can be caused by checking out with a partial or shallow clone, or when using Git submodules. You should disable git shallow clone to make sure the scanner has access to all of your history when running analysis with GitLab CI/CD.&#x20;

For more information, see [**Git shallow clone**](https://docs.gitlab.com/ee/ci/large_repositories/).
{% endhint %}

#### Setting environment variables <a href="#setting-environment-variables" id="setting-environment-variables"></a>

You can set environment variables securely for all pipelines in GitLab’s settings. See GitLab’s documentation on [CI/CD variables](https://docs.gitlab.com/ee/ci/variables/#creating-a-custom-environment-variable) for more information.

You need to set the following environment variables in GitLab for analysis:

* **Sonar Token**: Generate a SonarQube [generating-and-using-tokens](https://docs.sonarsource.com/sonarqube-server/10.5/user-guide/user-account/generating-and-using-tokens "mention") for GitLab and create a custom environment variable in GitLab with `SONAR_TOKEN` as the **Key** and the token you generated as the **Value**.
* **Sonar Host URL**: Create a custom environment variable with `SONAR_HOST_URL` as the **Key** and your SonarQube server URL as the **Value**.

#### Creating or updating the configuration file <a href="#creating-or-updating-the-configuration-file" id="creating-or-updating-the-configuration-file"></a>

**Configuring your properties file**

If required, when you select the option that describes your build, SonarQube provides you with a snippet to add to your properties file:

For example, for Gradle, the following samples are provided:

<details>

<summary>build.gradle</summary>

```css-79elbk
plugins {
  id "org.sonarqube" version "4.2.1.3168"
}

sonar {
  properties {
    property "sonar.projectKey", "projectKey"
    property "sonar.projectName", "projectName"
    property "sonar.qualitygate.wait", true 
  }
}
```

</details>

<details>

<summary>build.gradle.kts</summary>

```css-79elbk
plugins {
  id ("org.sonarqube") version "4.2.1.3168"
}

sonar {
  properties {
    property("sonar.projectKey", "projectKey")
    property("sonar.projectName", "projectName")
    property("sonar.qualitygate.wait", true)
  }
}
```

</details>

**Configuring your .gitlab-ci.yml file**

This section shows you how to configure your GitLab CI/CD `.gitlab-ci.yml` file. The `allow_failure` parameter in the examples allows a job to fail without impacting the rest of the CI suite.

You’ll set up your build according to your SonarQube edition: You’ll set up your build according to your SonarQube edition:

* **Community Edition**: Community Edition doesn’t support multiple branches, so you should only analyze your main branch. You can restrict the analysis to your main branch by using rules to add the branch name in your .yml file.
* **Developer Edition and above:** By default, GitLab will build all branches but not merge requests. To build merge requests, you need to use rules in your `.gitlab-ci.yml`. See the example configurations below for more information.

Select the scanner you’re using below to expand an example configuration:

<details>

<summary>SonarScanner for Gradle</summary>

```css-79elbk
sonarqube-check:
  image: gradle:8.2.0-jdk17-jammy
  variables:
    SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar"  # Defines the location of the analysis task cache
    GIT_DEPTH: "0"  # Tells git to fetch all the branches of the project, required by the analysis task
  cache:
    key: "${CI_JOB_NAME}"
    paths:
      - .sonar/cache
  script: gradle sonarqube -Dsonar.qualitygate.wait=true
  allow_failure: true
  rules:
    - if: $CI_COMMIT_REF_NAME == 'main' || $CI_PIPELINE_SOURCE == 'merge_request_event'
```

</details>

<details>

<summary>SonarScanner for Maven</summary>

```css-79elbk
sonarqube-check:
  image: maven:3.9.3-eclipse-temurin-17
  variables:
    SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar"  # Defines the location of the analysis task cache
    GIT_DEPTH: "0"  # Tells git to fetch all the branches of the project, required by the analysis task
  cache:
    key: "${CI_JOB_NAME}"
    paths:
      - .sonar/cache
  script:
    - mvn verify sonar:sonar -Dsonar.qualitygate.wait=true
  allow_failure: true
  rules:
    - if: $CI_COMMIT_REF_NAME == 'main' || $CI_PIPELINE_SOURCE == 'merge_request_event'
```

</details>

<details>

<summary>SonarScanner CLI</summary>

```css-79elbk
sonarqube-check:
  image:
    name: sonarsource/sonar-scanner-cli:latest
    entrypoint: [""]
  variables:
    SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar"  # Defines the location of the analysis task cache
    GIT_DEPTH: "0"  # Tells git to fetch all the branches of the project, required by the analysis task
  cache:
    key: "${CI_JOB_NAME}"
    paths:
      - .sonar/cache
  script:
    - sonar-scanner -Dsonar.qualitygate.wait=true
  allow_failure: true
  rules:
    - if: $CI_COMMIT_REF_NAME == 'main' || $CI_PIPELINE_SOURCE == 'merge_request_event'
```

**Project key**\
A project key has to be provided through `sonar-project.properties` or through the command line parameter. For more information, see the [sonarscanner](https://docs.sonarsource.com/sonarqube-server/10.5/analyzing-source-code/scanners/sonarscanner "mention") documentation.

**Self-signed certificates**\
If you secure your SonarQube instance with a self-signed certificate, you may need to build a custom image based on `sonarsource/sonar-scanner-cli`. See the section **Advanced docker configuration** within the [sonarscanner](https://docs.sonarsource.com/sonarqube-server/10.5/analyzing-source-code/scanners/sonarscanner "mention") documentation.

</details>

<details>

<summary>SonarScanner for .NET</summary>

**Configure your .gitlab-ci.yml file for .NET**

```css-79elbk
sonarqube-check:
  image: mcr.microsoft.com/dotnet/core/sdk:latest
  variables:
    SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar"  # Defines the location of the analysis task cache
    GIT_DEPTH: "0"  # Tells git to fetch all the branches of the project, required by the analysis task
  cache:
    key: "${CI_JOB_NAME}"
    paths:
      - .sonar/cache
  script: 
      - "apt-get update"
      - "apt-get install --yes openjdk-17-jre"
      - "dotnet tool install --global dotnet-sonarscanner"
      - "export PATH=\"$PATH:$HOME/.dotnet/tools\""
      - "dotnet sonarscanner begin /k:\"projectKey" /d:sonar.token=\"$SONAR_TOKEN\" /d:\"sonar.host.url=$SONAR_HOST_URL\" "  #Replace "projectKey" with your project key
      - "dotnet build"
      - "dotnet sonarscanner end /d:sonar.token=\"$SONAR_TOKEN\""
  allow_failure: true
  only:
    - merge_requests
    - master
    - main
    - develop
```

</details>

**C/C++/Objective-C configuration examples**

For some examples, you can refer to the [sonarsource-cfamily-examples](https://github.com/orgs/sonarsource-cfamily-examples/repositories?q=sq+gitlab) repository.

#### Failing the pipeline job when the quality gate fails <a href="#failing-the-pipeline-job-when-the-quality-gate-fails" id="failing-the-pipeline-job-when-the-quality-gate-fails"></a>

In order for the quality gate to fail on the GitLab side when it fails on the SonarQube side, the scanner needs to wait for the SonarQube quality gate status. To enable this, set the `sonar.qualitygate.wait=true` parameter in the `.gitlab-ci.yml` file.

You can set the `sonar.qualitygate.timeout` property to an amount of time (in seconds) that the scanner should wait for a report to be processed. The default is 300 seconds.

#### For more information <a href="#for-more-information" id="for-more-information"></a>

For more information on configuring your build with GitLab CI/CD, see the [GitLab CI/CD pipeline configuration reference](https://docs.gitlab.com/ci/yaml/).

### Reporting your quality gate status in GitLab <a href="#reporting-your-quality-gate-status-in-gitlab" id="reporting-your-quality-gate-status-in-gitlab"></a>

After you’ve set up SonarQube to import your GitLab projects as shown in the previous section, SonarQube can report your quality gate status and analysis metrics directly to GitLab.

To do this, add a project from GitLab by clicking the **Add project** button in the upper-right corner of the **Projects** homepage and select **GitLab** from the drop-down menu.

Then, follow the steps in SonarQube to analyze your project. SonarQube automatically sets the project settings required to show your quality gate in your merge requests.

{% hint style="info" %}
To report your quality gate status in your merge requests, a SonarQube analysis needs to be run on your code. You can find the additional parameters required for merge request analysis on the [pull-request-analysis](https://docs.sonarsource.com/sonarqube-server/10.5/analyzing-source-code/pull-request-analysis "mention") page.
{% endhint %}

If you’re creating your projects manually or adding quality gate reporting to an existing project, see the following section.

SonarQube can also report your quality gate status to GitLab merge requests for existing and manually-created projects. After you’ve updated your global settings as shown in the **Importing your GitLab projects into SonarQube** section above, set the following project settings at **Project Settings** > **General Settings** > **DevOps Platform Integration**:

* **Configuration name**: The configuration name that corresponds to your GitLab instance
* **Project ID**: your GitLab Project ID found in GitLab

### Preventing pull request merges when the quality gate fails <a href="#prevent-merges-when-quality-gate-fails" id="prevent-merges-when-quality-gate-fails"></a>

Once the previous section is done, you can block pull requests from being merged if it’s failing the quality gate :&#x20;

1. In your GitLab repository, go to ***Your project*** > **Settings** > **Merge requests**
2. In the **Merge Checks** section, select **Pipelines must succeed**.

More information about GitLab’s External status checks can be found in the [GitLab Documentation](https://docs.gitlab.com/ee/user/project/merge_requests/status_checks.html#block-merges-of-merge-requests-unless-all-status-checks-have-passed).

### Reporting vulnerabilities in GitLab <a href="#reporting-vulnerabilities-in-gitlab" id="reporting-vulnerabilities-in-gitlab"></a>

*This feature is available starting in* [*Developer Edition*](https://www.sonarsource.com/plans-and-pricing/developer/) *and requires GitLab Ultimate.*

SonarQube can provide feedback about security vulnerabilities inside the GitLab interface itself.  The security vulnerabilities found by SonarQube will appear on the **Gitlab** > **Vulnerability** report page.

#### Prerequisite <a href="#prerequisite" id="prerequisite"></a>

Make sure the user who owns the personal access token has **Browse** permission (see [security](https://docs.sonarsource.com/sonarqube-server/10.5/instance-administration/security "mention")).&#x20;

#### Configuring your .gitlab-ci.yml file <a href="#configuring-your-gitlabciyml-file" id="configuring-your-gitlabciyml-file"></a>

To activate this feature, add a vulnerability report stage to your `.gitlab-ci.yml` file, as follows:

<details>

<summary>SonarScanner for Gradle</summary>

```css-79elbk
stages:
    - sonarqube-check
    - vulnerability-report

sonarqube-check:
  stage: sonarqube-check
  image: gradle:8.2.0-jdk17-jammy
  variables:
    SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar"  # Defines the location of the analysis task cache
    GIT_DEPTH: "0"  # Tells git to fetch all the branches of the project, required by the analysis task
  cache:
    key: "${CI_JOB_NAME}"
    paths:
      - .sonar/cache
  script: gradle sonar
  allow_failure: true
  only:
    - merge_requests
    - master
    - main
    - develop

vulnerability-report:
  stage: vulnerability-report
  script:
    - 'curl -u "${SONAR_TOKEN}:" "${SONAR_HOST_URL}/api/issues/gitlab_sast_export?projectKey=<projectKey>&branch=${CI_COMMIT_BRANCH}&pullRequest=${CI_MERGE_REQUEST_IID}" -o gl-sast-sonar-report.json'  # Replace <projectKey> with your project key

  allow_failure: true
  only:
    - merge_requests
    - master
    - main
    - develop
  artifacts:
    expire_in: 1 day
    reports:
      sast: gl-sast-sonar-report.json
  dependencies:
    - sonarqube-check
```

</details>

<details>

<summary>SonarScanner for Maven</summary>

```css-79elbk
stages:
    - sonarqube-check
    - vulnerability-report

sonarqube-check:
  stage: sonarqube-check
  image: maven:3.9.3-eclipse-temurin-17
  variables:
    SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar"  # Defines the location of the analysis task cache
    GIT_DEPTH: "0"  # Tells git to fetch all the branches of the project, required by the analysis task
  cache:
    key: "${CI_JOB_NAME}"
    paths:
      - .sonar/cache
  script: 
    - mvn verify sonar:sonar
  allow_failure: true
  only:
    - merge_requests
    - master
    - main
    - develop

vulnerability-report:
  stage: vulnerability-report
  script:
    - 'curl -u "${SONAR_TOKEN}:" "${SONAR_HOST_URL}/api/issues/gitlab_sast_export?projectKey=<projectKey>&branch=${CI_COMMIT_BRANCH}&pullRequest=${CI_MERGE_REQUEST_IID}" -o gl-sast-sonar-report.json' # Replace <projectKey> with your project key
  allow_failure: true
  only:
    - merge_requests
    - master
    - main
    - develop
  artifacts:
    expire_in: 1 day
    reports:
      sast: gl-sast-sonar-report.json
  dependencies:
    - sonarqube-check
```

</details>

<details>

<summary>SonarScanner CLI</summary>

```css-79elbk
stages:
    - sonarqube-check
    - vulnerability-report

sonarqube-check:
  stage: sonarqube-check
  image: 
    name: sonarsource/sonar-scanner-cli:latest
    entrypoint: [""]
  variables:
    SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar"  # Defines the location of the analysis task cache
    GIT_DEPTH: "0"  # Tells git to fetch all the branches of the project, required by the analysis task
  cache:
    key: "${CI_JOB_NAME}"
    paths:
      - .sonar/cache
  script: 
    - sonar-scanner
  allow_failure: true
  only:
    - merge_requests
    - master
    - main
    - develop

vulnerability-report:
  stage: vulnerability-report
  script:
    - 'curl -u "${SONAR_TOKEN}:" "${SONAR_HOST_URL}/api/issues/gitlab_sast_export?projectKey=<projectKey>&branch=${CI_COMMIT_BRANCH}&pullRequest=${CI_MERGE_REQUEST_IID}" -o gl-sast-sonar-report.json'  # Replace <projectKey> with your project key
  allow_failure: true
  only:
    - merge_requests
    - master
    - main
    - develop
  artifacts:
    expire_in: 1 day
    reports:
      sast: gl-sast-sonar-report.json
  dependencies:
    - sonarqube-check
```

</details>

<details>

<summary>SonarScanner for .NET</summary>

```css-79elbk
stages:
    - sonarqube-check
    - vulnerability-report

sonarqube-check:
  stage: sonarqube-check
  image: mcr.microsoft.com/dotnet/core/sdk:latest
  variables:
    SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar"  # Defines the location of the analysis task cache
    GIT_DEPTH: "0"  # Tells git to fetch all the branches of the project, required by the analysis task
  cache:
    key: "${CI_JOB_NAME}"
    paths:
      - .sonar/cache
  script: 
      - "apt-get update"
      - "apt-get install --yes openjdk-17-jre"
      - "dotnet tool install --global dotnet-sonarscanner"
      - "export PATH=\"$PATH:$HOME/.dotnet/tools\""
      - "dotnet sonarscanner begin /k:\"projectKey" /d:sonar.token=\"$SONAR_TOKEN\" /d:\"sonar.host.url=$SONAR_HOST_URL\" "  # Replace "projectKey" with your project key
      - "dotnet build"
      - "dotnet sonarscanner end /d:sonar.token=\"$SONAR_TOKEN\""
  allow_failure: true
  only:
    - merge_requests
    - master
    - main
    - develop

vulnerability-report:
  stage: vulnerability-report
  script:
    - 'curl -u "${SONAR_TOKEN}:" "${SONAR_HOST_URL}/api/issues/gitlab_sast_export?projectKey=<projectKey>&branch=${CI_COMMIT_BRANCH}&pullRequest=${CI_MERGE_REQUEST_IID}" -o gl-sast-sonar-report.json'  # Replace <projectKey> with your project key
  allow_failure: true
  only:
    - merge_requests
    - master
    - main
    - develop
  artifacts:
    expire_in: 1 day
    reports:
      sast: gl-sast-sonar-report.json
  dependencies:
    - sonarqube-check
```

</details>

#### About synchronized status changes <a href="#about-synchronized-status-changes" id="about-synchronized-status-changes"></a>

Initially, all issues marked **Open** on SonarQube are marked as **Needs triage** on GitLab.&#x20;

When you update the status of an issue in SonarQube, it is also updated in GitLab.&#x20;

{% hint style="info" %}
Updating the status of an issue in Gitlab does not update it in SonarQube.
{% endhint %}

#### Correspondence of statuses <a href="#correspondence-of-statuses" id="correspondence-of-statuses"></a>

Because the available statuses on the two systems are not exactly the same, the following logic is used to manage the transitions:

|              |                      |
| ------------ | -------------------- |
| **GitLab**   | **SonarQube**        |
| Needs triage | Open                 |
| Confirm      | Confirm (deprecated) |
| Dismiss      | Accept               |
| Resolved     | Fixed                |

#### Severity mapping <a href="#severity-mapping" id="severity-mapping"></a>

The following table presents the severity levels in the two systems:

|            |               |
| ---------- | ------------- |
| **GitLab** | **SonarQube** |
| Critical   | High          |
| High       | High          |
| Medium     | Medium        |
| Low        | Low           |
| Info       | Low           |
| Unknown    | /             |

#### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

In Gitlab, your issues might appear duplicated after the modification of a file. We recommend using the **Activity** > **Still detected** filter in this case.

### If you’re using a monorepo <a href="#monorepo" id="monorepo"></a>

In a monorepo setup, multiple SonarQube projects, each corresponding to a separate project within the monorepo, are all bound to the same GitLab repository. If the GitLab integration with SonarQube has been properly set up, then you can easily import the projects managed in a GitLab monorepo from the SonarQube UI and thus, benefit from the integration features, such as reporting quality gate status to merge requests.&#x20;

The monorepo feature is supported starting in the [*Enterprise Edition*](https://www.sonarsource.com/plans-and-pricing/enterprise/).

#### Analysis setup roadmap <a href="#analysis-setup-roadmap" id="analysis-setup-roadmap"></a>

1. Create the SonarQube projects related to your monorepo: see [monorepos](https://docs.sonarsource.com/sonarqube-server/10.5/project-administration/monorepos "mention").
2. Add the analysis to your GitLab’s monorepo CI/CD pipeline: see below.
3. You can fail the pipeline when the quality gate fails and/or prevent merges when the quality gate fails: see above.&#x20;

#### Adding the SonarQube analysis to your monorepo pipeline <a href="#adding-the-sonarqube-analysis-to-your-monorepo-pipeline" id="adding-the-sonarqube-analysis-to-your-monorepo-pipeline"></a>

To add the SonarQube analysis to your GitLab’s monorepo CI/CD pipeline:

1. For each project in the monorepo, set the necessary analysis parameters: see [analysis-parameters](https://docs.sonarsource.com/sonarqube-server/10.5/analyzing-source-code/analysis-parameters "mention") and the respective SonarScanner page ([sonarscanner-for-gradle](https://docs.sonarsource.com/sonarqube-server/10.5/analyzing-source-code/scanners/sonarscanner-for-gradle "mention"), [sonarscanner-for-dotnet](https://docs.sonarsource.com/sonarqube-server/10.5/analyzing-source-code/scanners/sonarscanner-for-dotnet "mention"), [sonarscanner-for-maven](https://docs.sonarsource.com/sonarqube-server/10.5/analyzing-source-code/scanners/sonarscanner-for-maven "mention"), [sonarscanner](https://docs.sonarsource.com/sonarqube-server/10.5/analyzing-source-code/scanners/sonarscanner "mention")) for more information. The mandatory parameter is: `sonar.projectKey`  property.&#x20;
2. Set up the authentication to SonarQube Server: see below.
3. Add a CI/CD YAML syntax reference ( `.gitlab-ci.yml`) in the home directory of the monorepo: see below.

**Setting up the authentication to the SonarQube Server**

You have to create the Sonar tokens used to authenticate to the SonarQube Server during the analysis of the monorepo projects and store them securely in the pipeline environment. You can either use one single global-level token for the monorepo or use a project-level token for each project in the monorepo.&#x20;

Note that the Sonar Host URL variable must be set in GitLab as described above in **Analyzing projects with GitLab CI/CD > Setting environment variables**.

Proceed as follows:

1. Generate the [generating-and-using-tokens](https://docs.sonarsource.com/sonarqube-server/10.5/user-guide/user-account/generating-and-using-tokens "mention")(s) in SonarQube:
   * For project tokens, create a token for each project (you need the Administer permission on the project): Go to the **Security** page of your SonarQube account and create a **Project analysis token**.
   * For a global token, ask your administrator (The procedure is similar but you need the global Administer system permission.).
2. Create a [custom environment variable](https://docs.gitlab.com/ee/ci/variables/) in GitLab and set the **Key** as follows:
   * If you use a global token: enter SONAR\_TOKEN.
   * Otherwise: enter SONAR\_TOKEN\_1 (or another unique identifier within the monorepo) for the token of your first project in the monorepo
3. In the **Value** field, enter the corresponding token value.
4. If you use project-level tokens, repeat steps 2 to 3 for each additional project in the monorepo.

**Configuring a .gitlab-ci.yml file for the monorepo**

Define a job for each monorepo project in `.gitlab-ci.yml`.

### Advanced configuration <a href="#advanced-configuration" id="advanced-configuration"></a>

<details>

<summary>Configuring multiple DevOps platform instances</summary>

SonarQube can report your quality gate status to multiple DevOps platform instances. To do this, you need to create a configuration for each DevOps platform instance and assign that configuration to the appropriate projects.

* As part of [Developer Edition](https://www.sonarsource.com/plans-and-pricing/developer/), you can create one configuration for each DevOps platform.
* Starting in [*Enterprise Edition*](https://www.sonarsource.com/plans-and-pricing/enterprise/), you can create multiple configurations for each DevOps platform.&#x20;

</details>

<details>

<summary>Linking issues</summary>

When adding a quality gate status to your merge requests, individual issues will be linked to their SonarQube counterparts automatically. For this to work, you need to correctly set the instance’s **Server base URL** (**Administration** > **Configuration** > **General Settings** > **General** > **General**). Otherwise, the links will default to `localhost`.

</details>
