GitLab integration

SonarQube's integration with GitLab self-managed and GitLab.com 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, 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) See your quality gate and code metric results right in GitLab so you know if it's safe to merge your changes.

Prerequisites

• To integrate SonarQube with GitLab self-managed subscriptions, we recommend using GitLab version 15.6+.
• You've set a SonarQube Server base URL in Administration > Configuration > General Settings > General.

Branch analysis

Community Edition doesn't support the analysis of multiple branches, so you can only analyze your main branch. Starting in Developer Edition, you can analyze multiple branches and merge requests.

Authenticating with GitLab

See Authenticating with GitLab for more details on your authentication settings in GitLab. 

Importing your GitLab projects into SonarQube

Setting up the import of GitLab projects into SonarQube allows you to easily create SonarQube projects from your GitLab projects. If you're using Developer Edition or above, this is also the first step in adding merge request decoration.

To set up the import of GitLab projects:

1. Set your global settings
2. Add a personal access token for importing repositories

Setting your global settings

To import your GitLab projects into SonarQube, you need to first set your global SonarQube settings. Navigate to Administration > Configuration > General Settings > DevOps Platform Integrations, select the GitLab tab, and 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.
• Personal Access Token: A GitLab user account is used to decorate Merge Requests. We recommend using a dedicated GitLab account with at least Reporter permissions (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. Administrators can encrypt this token at Administration > Configuration > Encryption. See the Settings Encryption section of the Security page for more information. This personal access token is used to report your quality gate status to your pull requests. You'll be asked for another personal access token for importing projects in the following section.

Adding a personal access token for importing projects

After setting these global settings, you can add a project from GitLab by clicking the Add project button in the upper-right corner of the Projects homepage and selecting GitLab.

Then, you'll be asked to provide a personal access token with read_api scope so SonarQube can access and list your GitLab projects. This token will be stored in SonarQube and can be revoked at any time in GitLab.

After saving your personal access token, you'll see a list of your GitLab projects that you can set up to add to SonarQube. Setting up your projects this way also sets your project settings for merge request decoration.

For information on analyzing your projects with GitLab CI/CD, see the following section.

Analyzing projects with GitLab CI/CD

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 gilab-ci.yml file.

The following sections detail these steps.

Setting environment variables

You can set environment variables securely for all pipelines in GitLab's settings. See GitLab's documentation on CI/CD variables for more information.

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

• Sonar Token: Generate a SonarQube token 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

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:

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

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

plugins {
  id ("org.sonarqube") version "4.2.1.3168"
}

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

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

C/C++/Objective-C configuration examples

For some examples, you can refer to the sonarsource-cfamily-examples repository.

Failing the pipeline job 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.

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

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

Reporting your quality gate status in GitLab

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.

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

Reporting vulnerabilities in GitLab

This feature is available starting in Developer Edition 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

Make sure the user who owns the personal access token has Browse permission (see Security > Authentication > Project permissions). 

Configuring your gitlab.-ci.yml file

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

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

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

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

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

About synchronized status changes

Initially, all issues marked Open on SonarQube are marked as Needs triage on GitLab. 

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

Correspondence of statuses

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

Severity mapping

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

Troubleshooting

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

Advanced configuration