# Adding analysis to 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).

For more information on configuring your build with GitLab CI/CD, see the [GitLab CI/CD pipeline configuration reference](https://docs.gitlab.com/ee/administration/cicd/).

{% hint style="info" %}
A GitLab runner with a [Docker executor](https://docs.gitlab.com/runner/executors/#docker-executor) is required.
{% endhint %}

## Configuring the project analysis parameters <a href="#configuring-analysis-parameters" id="configuring-analysis-parameters"></a>

For general information, see [analysis-parameters](https://docs.sonarsource.com/sonarqube-community-build/analyzing-source-code/analysis-parameters "mention") and the respective SonarScanner section: [sonarscanner-for-maven](https://docs.sonarsource.com/sonarqube-community-build/analyzing-source-code/scanners/sonarscanner-for-maven "mention"), [sonarscanner-for-gradle](https://docs.sonarsource.com/sonarqube-community-build/analyzing-source-code/scanners/sonarscanner-for-gradle "mention"), [using](https://docs.sonarsource.com/sonarqube-community-build/analyzing-source-code/scanners/dotnet/using "mention"), [sonarscanner](https://docs.sonarsource.com/sonarqube-community-build/analyzing-source-code/scanners/sonarscanner "mention"), and [configuring](https://docs.sonarsource.com/sonarqube-community-build/analyzing-source-code/scanners/npm/configuring "mention").

With GitLab CI/CD, you can securely set `sonar.token` and `sonar.host.url` properties through [CI/CD variables](https://docs.gitlab.com/ee/ci/variables/#creating-a-custom-environment-variable): see the [#setting-the-authentication-to-the-sonarqube-community-build](#setting-the-authentication-to-the-sonarqube-community-build "mention") expandable below.

<details>

<summary>Setting the authentication to the SonarQube Community Build</summary>

You have to create the Sonar token used to authenticate to the SonarQube Community Build during the project analysis and store it securely in the pipeline environment. You can either use a global-level or (recommended) project-level token.

Proceed as follows:

1. Generate the token in SonarQube Community Build:
   * For a project token, go to the Security page of your SonarQube Community Build account and create a token.
   * For a global token, ask your system administrator (The procedure is similar but you need the global Administer system permission.).
2. Create a [custom environment variable](https://docs.gitlab.com/ee/ci/variables/) in GitLab with:
   * Key: `SONAR_TOKEN`
   * Value: the corresponding token value.
3. Create a custom environment variable in GitLab with:
   * Key: `SONAR_HOST_URL`
   * Value: SonarQube Community Build URL

</details>

## Configuring your .gitlab-ci-yml file <a href="#configuring-yml-file" id="configuring-yml-file"></a>

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.

The SonarQube Community Build 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.

Select the scanner you’re using below to expand an example configuration:

<details>

<summary>SonarScanner for Gradle</summary>

```yaml
sonarqube-check:
  image: gradle:8.10.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: false
  rules:
    - if: $CI_COMMIT_REF_NAME == 'main' || $CI_PIPELINE_SOURCE == 'merge_request_event'
```

</details>

<details>

<summary>SonarScanner for Maven</summary>

```yaml
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 org.sonarsource.scanner.maven:sonar-maven-plugin:sonar -Dsonar.qualitygate.wait=true
  allow_failure: false
  rules:
    - if: $CI_COMMIT_REF_NAME == 'main' || $CI_PIPELINE_SOURCE == 'merge_request_event'
```

</details>

<details>

<summary>SonarScanner CLI</summary>

```yaml
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: false
  rules:
    - if: $CI_COMMIT_REF_NAME == 'main' || $CI_PIPELINE_SOURCE == 'merge_request_event'
```

**Project key**\
A project key has to be provided through `sonar-project.properties` or through the command line parameter. For more information, see the [sonarscanner](https://docs.sonarsource.com/sonarqube-community-build/analyzing-source-code/scanners/sonarscanner "mention") documentation.

**Self-signed certificates**\
If you secure your SonarQube Community Build instance with a self-signed certificate, you may need to build a custom image based on `sonarsource/sonar-scanner-cli`. See the section **Advanced docker configuration** within the [sonarscanner](https://docs.sonarsource.com/sonarqube-community-build/analyzing-source-code/scanners/sonarscanner "mention") documentation.

</details>

<details>

<summary>SonarScanner for .NET</summary>

Configure your .gitlab-ci.yml file for .NET.

```yaml
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:\"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: false
  only:
    - merge_requests
    - main
    - develop
```

</details>

{% hint style="info" %}
For C/C++/Objective-C configuration examples, you can refer to the [sonarsource-cfamily-examples](https://github.com/orgs/sonarsource-cfamily-examples/repositories?q=sq+gitlab) repository.
{% endhint %}

{% hint style="warning" %}
The errors "*Missing blame information…*" and "*Could not find ref…*" can be caused by checking out with a partial or shallow clone, or when using Git submodules. You should disable git shallow clone to make sure the scanner has access to all of your history when running analysis with GitLab CI/CD.

For more information, see [Git shallow clone](https://docs.gitlab.com/ee/user/project/repository/monorepos/#shallow-cloning).
{% endhint %}

## Failing the pipeline when the quality gate fails <a href="#failing-pipeline" id="failing-pipeline"></a>

In order for the quality gate to fail on the GitLab side when it fails on the SonarQube Community Build side, the scanner needs to wait for the SonarQube Community Build 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.