Skip to content

GitLab CI template for SonarQube

This project implements a GitLab CI/CD template to continuously inspect your codebase with SonarQube.

SonarQube is a Code Quality and Security tool that helps you analyse your source code and detect quality issues or security vulnerabilities as early as possible.


This template can be used both as a CI/CD component or using the legacy include:project syntax.

Use as a CI/CD component

Add the following to your gitlab-ci.yml:

  # 1: include the component
  - component:
    # 2: set/override component inputs
      host-url: # ⚠ this is only an example

Use as a CI/CD template (legacy)

Add the following to your gitlab-ci.yml:

  # 1: include the template
  - project: 'to-be-continuous/sonar'
    ref: '4.2.3'
    file: '/templates/gitlab-ci-sonar.yml'

  # 2: set/override template variables
  SONAR_HOST_URL: # ⚠ this is only an example

SonarQube analysis job

This job performs a SonarQube analysis of your code.

It is bound to the test stage, and uses the following variables:

Input / Variable Description Default value
scanner-image / SONAR_SCANNER_IMAGE The Docker image used to run sonar-scanner
host-url / SONAR_HOST_URL SonarQube server url none (disabled)
project-key / SONAR_PROJECT_KEY SonarQube Project Key (might also be set in the file) fallbacks to $CI_PROJECT_PATH_SLUG (see below)
project-name / SONAR_PROJECT_NAME SonarQube Project Name (might also be set in the file) fallbacks to $CI_PROJECT_PATH (see below)
🔒 SONAR_TOKEN SonarQube authentication token (depends on your authentication method) none
🔒 SONAR_LOGIN SonarQube login (depends on your authentication method) none
🔒 SONAR_PASSWORD SonarQube password (depends on your authentication method) none
base-args / SONAR_BASE_ARGS SonarQube analysis arguments -Dsonar.links.homepage=${CI_PROJECT_URL}${CI_PROJECT_URL}/-/pipelines -Dsonar.links.issue=${CI_PROJECT_URL}/-/issues
quality-gate-enabled / SONAR_QUALITY_GATE_ENABLED Set to true to enable SonarQube Quality Gate verification.
Uses sonar.qualitygate.wait parameter (see doc).
none (disabled)

Automatic Branch Analysis & Merge Request Analysis

This template relies on SonarScanner's GitLab integration, that is able to auto-detect whether to launch Branch Analysis or Merge Request Analysis from GitLab's environment variables.

⚠ This feature also depends on your SonarQube server version and license. If using Community Edition, you'll have to install the sonarqube-community-branch-plugin to enable automatic Branch & Merge Request analysis (only works from SonarQube version 8).

⚠ Merge Request Analysis only works if you're running Merge Request pipeline strategy (default).

Configuring SonarQube project key, project name and other parameters

You shall define your SonarQube project key and project name in a file located at the root of your repository (as respectively sonar.projectKey and sonar.projectName entries), although they might alternately be set as $SONAR_PROJECT_KEY and $SONAR_PROJECT_NAME variables.

Note that when not explictly set, the template will use $CI_PROJECT_PATH_SLUG and $CI_PROJECT_PATH as fallback project key and project name.

The file is also the recommended way to configure other SonarQube analysis parameters as well as language specific parameters.

Each to-be-continuous build template shall briefly document the supported language-specific SonarQube parameters.


Vault variant

This variant allows delegating your secrets management to a Vault server.


In order to be able to communicate with the Vault server, the variant requires the additional configuration parameters:

Input / Variable Description Default value
TBC_VAULT_IMAGE The Vault Secrets Provider image to use (can be overridden)
vault-base-url / VAULT_BASE_URL The Vault server base API url none
vault-oidc-aud / VAULT_OIDC_AUD The aud claim for the JWT $CI_SERVER_URL
🔒 VAULT_ROLE_ID The AppRole RoleID must be defined
🔒 VAULT_SECRET_ID The AppRole SecretID must be defined


Then you may retrieve any of your secret(s) from Vault using the following syntax:



Parameter Description
secret_path (path parameter) this is your secret location in the Vault server
field (query parameter) parameter to access a single basic field from the secret JSON payload


  # main template
  - component:
  # Vault variant
  - component:
       # audience claim for JWT
      vault-oidc-aud: ""
      vault-base-url: ""

  # Secrets managed by Vault
  SONAR_TOKEN: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/my-app/sonar?field=token"
  # $VAULT_ROLE_ID and $VAULT_SECRET_ID defined as a secret CI/CD variable