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.

Usage¶

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:

include:
  # 1: include the component
  - component: $CI_SERVER_FQDN/to-be-continuous/sonar/gitlab-ci-sonar@4.2.4
    # 2: set/override component inputs
    inputs:
      host-url: https://sonarqube.acme.host # ⚠ this is only an example

Use as a CI/CD template (legacy)¶

Add the following to your .gitlab-ci.yml:

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

variables:
  # 2: set/override template variables
  SONAR_HOST_URL: https://sonarqube.acme.host # ⚠ 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	`registry.hub.docker.com/sonarsource/sonar-scanner-cli:latest`
`host-url` / `SONAR_HOST_URL`	SonarQube server url	none (disabled)
`project-key` / `SONAR_PROJECT_KEY`	SonarQube Project Key (might also be set in the `sonar-project.properties` file)	fallbacks to `$CI_PROJECT_PATH_SLUG` (see below)
`project-name` / `SONAR_PROJECT_NAME`	SonarQube Project Name (might also be set in the `sonar-project.properties` 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} -Dsonar.links.ci=${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 sonar-project.properties 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 sonar-project.properties 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.

Variants¶

Vault variant¶

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

Configuration¶

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)	`registry.gitlab.com/to-be-continuous/tools/vault-secrets-provider:latest`
`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

Usage¶

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

@url@http://vault-secrets-provider/api/secrets/{secret_path}?field={field}

With:

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

Example¶

include:
  # main template
  - component: $CI_SERVER_FQDN/to-be-continuous/sonar/gitlab-ci-sonar@4.2.4
  # Vault variant
  - component: $CI_SERVER_FQDN/to-be-continuous/sonar/gitlab-ci-sonar-vault@4.2.4
    inputs:
       # audience claim for JWT
      vault-oidc-aud: "https://vault.acme.host"
      vault-base-url: "https://vault.acme.host/v1"

variables:
  # 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