GitLab CI

Configure an analysis of your SonarQube Cloud project using GitLab CI.

You can integrate SonarQube Cloud analysis into your GitLab CI pipeline.

A GitLab runner with a Docker executor is required.

Add environment variables

Define the SONAR_TOKEN environment variable

Generate a token with the Execute analysis permission. See:

• From the Team plan: Managing Scoped Organization Tokens.

• With the Free plan: Managing Personal Access Tokens.

In GitLab, go to Settings and then CI/CD Variables to add the following variable and make sure it is available for your project:

• In the Key field, enter SONAR_TOKEN

• In the Value field, enter the token you generated on SonarQube Cloud

• Tick the Masked checkbox (this will prevent GitLab from showing the token in your build logs)

Define the SONAR_HOST_URL environment variable

In GitLab, go to Settings and then CI/CD Variables to add the following variable and make sure it is available for your project. You can define it for each of your GitLab projects or only once on the parent GitLab group.

• In the Key field, enter SONAR_HOST_URL

• In the Value field, enter https://sonarcloud.io

• No need to select the Masked checkbox this time

Create or update the gitlab-ci.yml file

Choose the build technology relevant to your project:

Gradle

plugins {
  id "org.sonarqube" version "6.3.1.5724"
}

sonarqube {
  properties {
    property "sonar.projectKey", "<YourProjectKey>"
    property "sonar.organization", "<YourOrganizationKey>"
  }
}

Create or update your .gitlab-ci.yml file with the following content:

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
sonarcloud-check:
 image: gradle:alpine
 cache:
   key: "${CI_JOB_NAME}"
   paths:
     - .sonar/cache
 script: gradle sonarqube
 rules:
    - if: $CI_COMMIT_REF_NAME == 'main' || $CI_PIPELINE_SOURCE == 'merge_request_event'

Maven

Update your pom.xml file with the following properties:

<properties>
   <sonar.projectKey>your-project-key-here</sonar.projectKey>
   <sonar.organization>your-sonarcloud-organization-key-here</sonar.organization>
 </properties>

Create or update your .gitlab-ci.yml file with the following content:

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
sonarcloud-check:
  image: maven:3.9.3-eclipse-temurin-17
  cache:
    key: "${CI_JOB_NAME}"
    paths:
      - .sonar/cache
  script:
    - mvn verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar
  rules:
    - if: $CI_COMMIT_REF_NAME == 'main' || $CI_PIPELINE_SOURCE == 'merge_request_event'

Other (for JS, TS, Go, Python, PHP, …)

Create or update your .gitlab-ci.yml file with the following content.

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
sonarcloud-check:
 image:
   name: sonarsource/sonar-scanner-cli:latest
   entrypoint: [""]
 cache:
   key: "${CI_JOB_NAME}"
   paths:
     - .sonar/cache
 script:
   - sonar-scanner
 rules:
    - if: $CI_COMMIT_REF_NAME == 'main' || $CI_PIPELINE_SOURCE == 'merge_request_event'

Create a sonar-project.properties file in the root directory of the project:

sonar.projectKey=your-project-key-here
sonar.organization=your-sonarcloud-organization-key-here

# This is the name and version displayed in the SonarQube Cloud UI.
# sonar.projectName=Sample Project
# sonar.projectVersion=1.0

# Path is relative to the sonar-project.properties file. Replace "\" by "/" on Windows.
# sonar.sources=.

# Encoding of the source code. Default is default system encoding
# sonar.sourceEncoding=UTF-8

.NET

Create or update your .gitlab-ci.yml file with the following content:

sonarqube-check:
  image: mcr.microsoft.com/dotnet/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: 
    - dotnet tool install --global dotnet-sonarscanner
    - export PATH="$PATH:$HOME/.dotnet/tools"
    - dotnet sonarscanner begin /k:"<YourProjectKey>" /o:"<YourOrganizationKey>" /d:sonar.token="$SONAR_TOKEN"
 #Replace <YourProjectKey> with your project key and <YourOrganizationKey> with your organization key
    - dotnet build
    - dotnet sonarscanner end /d:sonar.token="$SONAR_TOKEN"
  allow_failure: false
  only:
    - merge_requests
    - master
    - main
    - develop

Failing the pipeline job when the SonarQube Cloud Quality Gate fails

In order for the pipeline to stop on GitLab CI side when the Quality Gate fails on SonarQube Cloud side, the SonarScanner needs to wait for the report and Quality Gate status to be processed by SonarQube Cloud. To enable this feature, you can set the sonar.qualitygate.wait=true parameter in your sonar-project.properties or .gitlab-ci.yml file.

You can also set the sonar.qualitygate.timeout property to a maximum amount of time (in seconds) that the SonarScanner should wait for a report to be processed. The default is 300 seconds. Reaching this timeout will count as a failure and stop the GitLab CI pipeline.

It is also possible to allow a job to fail without impacting the rest of the CI suite with the allow_failure: true parameter of GitLab CI. The failing job won’t stop the pipeline but will be displayed as in a warning state.

Merge request decoration

The decoration of your merge requests is automatically configured as soon as you import a project and set up your GitLab CI.

The same access token used for connecting your GitLab group to SonarQube Cloud is used to post comments on the merge request. It makes it all the more important to use a technical GitLab account to generate the token.

Analyzing Monorepo Projects: Build Configuration

The example below shows how you could set up a yml file for multiple projects in a monorepo. If you want to analyze a monorepo that contains more than one project ensure that you specify the paths to each sub-project for analysis in your build file.

To ensure that your monorepo works as expected, you need to build each project in the monorepo separately with a valid token. Each project of the monorepo can be configured with its own properties file. Gitlab only accepts one SONAR_TOKEN (in the CI/CD Variables configuration) per Gitlab project so you do not need to pass tokens for each project within your monorepo.

See the section on environment variables at the top of this page for more information on setting up your token.

Below is a sample .gitlab-ci.yml file that assumes your build requires the Sonar Scanner CLI, see the examples above if your setup uses an alternative configuration.

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


sonarcloud-check-project-1:
  image:
    name: sonarsource/sonar-scanner-cli:latest
    entrypoint: [""]
  cache:
    key: "${CI_JOB_NAME}"
    paths:
      - .sonar/cache
  script:
    - sonar-scanner -Dsonar.sources=project-1 -Dsonar.organization=... -Dsonar.projectKey=...
  rules:
    - if: $CI_COMMIT_REF_NAME == 'main' || $CI_PIPELINE_SOURCE == 'merge_request_event'

sonarcloud-check-project-2:
  image:
    name: sonarsource/sonar-scanner-cli:latest
    entrypoint: [""]
  cache:
    key: "${CI_JOB_NAME}"
    paths:
      - .sonar/cache
  script:
    - sonar-scanner -Dsonar.sources=project-2 -Dsonar.organization=... -Dsonar.projectKey=...
  rules:
    - if: $CI_COMMIT_REF_NAME == 'main' || $CI_PIPELINE_SOURCE == 'merge_request_event'