Adding the SonarQube analysis to your GitLab CI/CD pipeline

Once you have created your project in SonarQube, you can add the SonarQube analysis to your GitLab CI/CD pipeline:

1. Configure the project analysis parameters.
2. Add the analysis to your GitLab CI/CD pipeline.
3. Commit and push your code to start the analysis.

You can fail the pipeline when the quality gate fails (see below). If you use a monorepo, see the section If you use a monorepo below. To manage other project-level features, see Setting up GitLab integration features at the project level.

For more information on configuring your build with GitLab CI/CD, see the GitLab CI/CD pipeline configuration reference.

Configuring the project analysis parameters

For general information, see Analysis parameters and the respective SonarScanner section: Maven, Gradle, NET, CLI, and NPM. 

With GitLab CI/CD, you can securely set sonar.token and sonar.host.url properties through CI/CD variables: see Setting the authentication to the SonarQube Server below.

In addition, starting from the Developer Edition, SonarScanners running in GitLab CI/CD can automatically detect branches and merge requests being built so you don't need to specifically pass them as parameters to the scanner. See Branch analysis and Pull request analysis for more information.

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:

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'

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'

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'

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

Failing the pipeline when the quality gate fails

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. See the configuration examples in Configuring your .gitlab-ci-yml file above.

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.

If you use a monorepo

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. 

The monorepo feature is supported starting in the Enterprise Edition.

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

1. If not already done, create the SonarQube projects related to your monorepo: see Managing the projects of a monorepo. To set up integration features at project level, see Setting up GitLab integration features at the project level.
2. For each project in the monorepo:
   • Set up the authentication to SonarQube Server (sonar.token and sonar.host.url properties): see Setting up the authentication to the SonarQube Server below.
   • Set the other necessary analysis parameters: see Configuring the project analysis parameters above. The mandatory parameter is:  sonar.projectKey  property. 
3. Add a CI/CD YAML syntax reference ( .gitlab-ci.yml) in the home directory of the monorepo: Define a job for each monorepo project in .gitlab-ci.yml.
4. You can fail the pipeline when the quality gate fails: see above.