From 744f6da1f4e6161fd77a350cb91750a858b32d6e Mon Sep 17 00:00:00 2001 From: michaelbirnstiehl Date: Thu, 27 Aug 2020 15:48:21 -0500 Subject: [PATCH] SONAR-13828 Update GitLab CI/CD docs for GitLab Tutorial --- .../src/pages/analysis/gitlab-cicd.md | 90 ++++++++++--------- 1 file changed, 50 insertions(+), 40 deletions(-) diff --git a/server/sonar-docs/src/pages/analysis/gitlab-cicd.md b/server/sonar-docs/src/pages/analysis/gitlab-cicd.md index 93cd72ae01b..ec5f942da36 100644 --- a/server/sonar-docs/src/pages/analysis/gitlab-cicd.md +++ b/server/sonar-docs/src/pages/analysis/gitlab-cicd.md @@ -18,88 +18,98 @@ Because Community Edition doesn't support multiple branches, you should only ana ### Developer Edition and above By default, GitLab will build all branches but not Merge Requests. To build Merge Requests, you need to update the `.gitlab-ci.yml` file by adding `merge_requests` to the `only` parameter. See the example configurations below for more information. -## Failing the pipeline job when the SonarQube Quality Gate fails -In order for the Quality Gate to fail on the GitLab side when the Quality Gate 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. +## Analyzing your repository -See the example configurations below for more information. - -## Example configurations -The following example configurations show you how to configure the execution of SonarScanner for Gradle, SonarScanner for Maven, and SonarScanner CLI with GitLab CI/CD. +### Setting environment variables +You can set environment variables securely for all pipelines in GitLab's settings. See [Creating a Custom Environment Variable](https://docs.gitlab.com/ee/ci/variables/#creating-a-custom-environment-variable) for more information. + +You need to set the following environment variables in GitLab for analysis: + +- `SONAR_TOKEN` – Generate a SonarQube [token](/user-guide/user-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**. -In the example configurations: +- `SONAR_HOST_URL` – Create a custom environment variable with `SONAR_HOST_URL` as the **Key** and your SonarQube server URL as the **Value**. -The `allow_failure` parameter allows a job to fail without impacting the rest of the CI suite. +### Configuring your `gitlab-ci.yml` file +The following examples show you how to configure your GitLab CI/CD `gitlab-ci.yml` file. -The `SONAR_TOKEN` and `SONAR_HOST_URL` variables are included. If you don't have environment variables set for all builds in GitLab's settings (as shown in **Setting environment variables for all builds** below), you need to set the variables to pass a [token](/user-guide/user-token/) and the URL of your SonarQube server. +In the following examples, the `allow_failure` parameter allows a job to fail without impacting the rest of the CI suite. -Click your scanner below to see the example configuration: +Click your scanner below to expand the example configuration: [[collapse]] -| ## SonarScanner for Gradle: +| ## SonarScanner for Gradle | ``` -| image: gradle:alpine -| variables: -| SONAR_TOKEN: "your-sonarqube-token" -| SONAR_HOST_URL: "http://your-sonarqube-instance.org" -| GIT_DEPTH: 0 | sonarqube-check: -| stage: test +| image: gradle:jre11-slim +| 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 | only: | - merge_requests | - master +| - develop | ``` [[collapse]] -| ## SonarScanner for Maven: +| ## SonarScanner for Maven | | ``` -| image: maven:latest -| variables: -| SONAR_TOKEN: "your-sonarqube-token" -| SONAR_HOST_URL: "http://your-sonarqube-url" -| GIT_DEPTH: 0 | sonarqube-check: +| image: maven:3.6.3-jdk-11 +| 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 | only: | - merge_requests | - master +| - develop | ``` [[collapse]] -| ## SonarScanner CLI: +| ## SonarScanner CLI | | ``` -| image: -| name: sonarsource/sonar-scanner-cli:latest -| variables: -| SONAR_TOKEN: "your-sonarqube-token" -| SONAR_HOST_URL: "http://your-sonarqube-instance.org" -| 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 | sonarqube-check: -| stage: test +| 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 | only: | - merge_requests | - master +| - develop | ``` | | **Note:** A project key has to be provided through `sonar-project.properties` or through the command line parameter. For more information, see the [SonarScanner](/analysis/scan/sonarscanner/) documentation. -## Setting environment variables for all builds -Instead of specifying environment variables in your `.gitlab-ci.yml` file (such as `SONAR_TOKEN` and `SONAR_HOST_URL`), you can set them securely for all pipelines in GitLab's settings. See [Creating a Custom Environment Variable](https://docs.gitlab.com/ee/ci/variables/#creating-a-custom-environment-variable) for more information. +### Failing the pipeline job when the SonarQube Quality Gate fails +In order for the Quality Gate to fail on the GitLab side when the Quality Gate 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. + +See the example configurations below for more information. ## For more information For more information on configuring your build with GitLab CI/CD, see the [GitLab CI/CD Pipeline Configuration Reference](https://gitlab.com/help/ci/yaml/README.md). -- 2.39.5