SONAR-12631 Add Quality Gate check in GitLab documentation

diff --git a/server/sonar-docs/src/pages/analysis/gitlab-cicd.md b/server/sonar-docs/src/pages/analysis/gitlab-cicd.md
index 9871164bf670749ed010086a32c625bd92f9c661..beec052e9ae98a8d766b37817a796821b37f9d00 100644 (file)
--- a/server/sonar-docs/src/pages/analysis/gitlab-cicd.md
+++ b/server/sonar-docs/src/pages/analysis/gitlab-cicd.md
@@ -5,19 +5,35 @@ url: /analysis/gitlab-cicd/
 
 _Merge Request analysis is available as part of [Developer Edition](https://redirect.sonarsource.com/editions/developer.html) and [above](https://www.sonarsource.com/plans-and-pricing/)._
 
-SonarScanners running in GitLab CI/CD Jobs will automatically detect branches or Merge Requests being built so you don't need to specifically pass them as parameters to the scanner. 
+SonarScanners running in GitLab CI/CD Jobs will automatically detect branches or Merge Requests being built so you don't need to specifically pass them as parameters to the scanner.
+
+[[warning]]
+| You need to disable shallow clone to make sure the scanner has access to all of the branches when running analysis with GitLab CI/CD. See [Git shallow clone](https://docs.gitlab.com/ee/user/project/pipelines/settings.html#git-shallow-clone) for more on disabling shallow clone.
 
 ## Activating builds  
-By default, GitLab will build all branches but not Merge Requests.
+Set up your build according to the section below that corresponds to your SonarQube edition.
 
 ### Developer Edition and above
-To build Merge Requests, you need to update the `.gitlab-ci.yml` file by adding `merge_requests` to the `only` parameter. See the following examples for more information.
+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.
 
 ### Community Edition
-Because Community Edition doesn't support branches, you should only analyze your main branch. You can restrict analysis to that branch by adding the branch name to the `only` parameter.
+Because Community Edition doesn't support branches, you should only analyze your main branch. You can restrict analysis to your main branch by adding the branch name to the `only` parameter.
+
+## 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.
 
 ## Example configurations
-The following examples show you how to configure the execution of SonarScanner for Gradle, SonarScanner for Maven, and SonarScanner CLI with GitLab CI/CD.
+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.
+
+In the example configurations:
+
+The `allow_failure` parameter allows a job to fail without impacting the rest of the CI suite.
+
+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.
 
 ### SonarScanner for Gradle:
 
@@ -28,7 +44,8 @@ variables:
   SONAR_HOST_URL: "http://your-sonarqube-instance.org"
 sonarqube-check:
   stage: test
-  script: gradle sonarqube
+  script: gradle sonarqube -Dsonar.qualitygate.wait=true
+  allow_failure: true
   only:
     - merge_requests
     - branches
@@ -41,9 +58,10 @@ image: maven:latest
 variables:
   SONAR_TOKEN: "your-sonarqube-token"
   SONAR_HOST_URL: "http://your-sonarqube-url"
-sonarqube-scan:
+sonarqube-check:
   script:
-    - mvn verify sonar:sonar
+    - mvn verify sonar:sonar -Dsonar.qualitygate.wait=true
+  allow_failure: true
   only:
     - merge_requests
     - branches
@@ -61,13 +79,14 @@ variables:
 sonarqube-check:
   stage: test
   script:
-    - sonar-scanner
+    - sonar-scanner -Dsonar.qualitygate.wait=true
+  allow_failure: true
   only:
     - merge_requests
     - branches
 ```  
 
-**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/) page.
+**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.