From 957643374bfc107a6bc24e8519c260cbb7139edd Mon Sep 17 00:00:00 2001
From: Zart Colwing <zartc@wanadoo.fr>
Date: Tue, 10 Oct 2023 09:50:57 +0000
Subject: [PATCH] docs: detailed SonarQube configuration instructions (with
SonarCloud requirements)
---
README.md | 45 ++++++++++++++++++++++++++++++++++++---------
1 file changed, 36 insertions(+), 9 deletions(-)
diff --git a/README.md b/README.md
index f770a9c..53ea635 100644
--- a/README.md
+++ b/README.md
@@ -78,22 +78,47 @@ More info:
### `mvn-sonar` job — SonarQube analysis
-This job is **disabled by default** and performs a SonarQube analysis of your code.
-
-The job is bound to the `test` stage and uses the following variables:
+This job, **disabled by default**, is bound to the `test` stage and performs a SonarQube analysis of your code.
+This job uses the following variables:
| Name | description | default value |
| ------------------------ | -------------------------------------- | ----------------- |
| `SONAR_HOST_URL` | SonarQube server url | _none_ (disabled) |
-| :lock: `SONAR_TOKEN` | SonarQube authentication [token](https://docs.sonarqube.org/latest/user-guide/user-token/) (depends on your authentication method) | _none_ |
-| :lock: `SONAR_LOGIN` | SonarQube login (depends on your authentication method) | _none_ |
+| :lock: `SONAR_TOKEN` | SonarQube authentication [token](https://docs.sonarsource.com/sonarqube/latest/user-guide/user-account/generating-and-using-tokens/#using-a-token) (depends on your authentication method) | _none_ |
+| :lock: `SONAR_LOGIN` | SonarQube [login](https://docs.sonarsource.com/sonarqube/latest/extension-guide/web-api/#http-basic-access) (depends on your authentication method) | _none_ |
| :lock: `SONAR_PASSWORD` | SonarQube password (depends on your authentication method) | _none_ |
-| `SONAR_BASE_ARGS` | SonarQube [analysis arguments](https://docs.sonarqube.org/latest/analysis/analysis-parameters/) | `sonar:sonar -Dsonar.links.homepage=${CI_PROJECT_URL} -Dsonar.links.ci=${CI_PROJECT_URL}/-/pipelines -Dsonar.links.issue=${CI_PROJECT_URL}/-/issues` |
-| `SONAR_QUALITY_GATE_ENABLED` | Set to `true` to enable SonarQube [Quality Gate](https://docs.sonarqube.org/latest/user-guide/quality-gates/) verification.<br/>_Uses `sonar.qualitygate.wait` parameter ([see doc](https://docs.sonarqube.org/latest/analysis/ci-integration-overview/#header-1))._ | _none_ (disabled) |
+| `SONAR_BASE_ARGS` | SonarQube [analysis arguments](https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/analysis-parameters/) | `sonar:sonar -Dsonar.links.homepage=${CI_PROJECT_URL} -Dsonar.links.ci=${CI_PROJECT_URL}/-/pipelines -Dsonar.links.issue=${CI_PROJECT_URL}/-/issues` |
+| `SONAR_QUALITY_GATE_ENABLED` | Set to `true` to enable SonarQube [Quality Gate](https://docs.sonarsource.com/sonarqube/latest/user-guide/quality-gates/) verification.<br/>_Uses `sonar.qualitygate.wait` parameter ([see doc](https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/ci-integration/overview/#quality-gate-fails))._ | _none_ (disabled) |
+
+#### Recommended minimal configuration
+
+1. set the `SONAR_HOST_URL` value either in your `.gitlab-ci.yml` file or as a project or group variable (:warning: setting it as a group variable will enable the SonarQube analysis for all the children projects),
+2. define your SonarQube credentials (:lock: `SONAR_TOKEN` or `SONAR_LOGIN` & :lock: `SONAR_PASSWORD`) as project or group variables,
+3. configure the project SonarQube settings in the `pom.xml` file (:warning: the [SonarScanner for Maven](https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/scanners/sonarscanner-for-maven/#configuring-analysis) completely ignores the `sonar-project.properties` file):
+ ```xml
+ <properties>
+ <!-- the SonarQube project key -->
+ <sonar.projectKey>write-key-here</sonar.projectKey>
+ <!-- additional SonarQube settings can go here -->
+ ...
+ </properties>
+ ```
+ More info about [SonarQube settings](https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/scanners/sonarscanner-for-maven/#analyzing)
+
+:warning: if using [SonarCloud](https://sonarcloud.io/) (a cloud-based SonarQube-as-a-Service), you'll have to define the additional `sonar.organization` property ([see mandatory-parameters](https://docs.sonarcloud.io/advanced-setup/analysis-parameters/#mandatory-parameters)).
+
+:information_source: As SonarCloud determined the `organization` and `projectKey` properties from the project's GitLab context when importing the project, you can reuse the predefined GitLab variables as follows in your `pom.xml`:
+```xml
+<properties>
+ <!-- SonarCloud settings -->
+ <sonar.organization>${env.CI_PROJECT_ROOT_NAMESPACE}</sonar.organization>
+ <sonar.projectKey>${env.CI_PROJECT_ROOT_NAMESPACE}_${env.CI_PROJECT_NAME}</sonar.projectKey>
+</properties>
+```
#### Automatic Branch Analysis & Merge Request Analysis
-This template relies on SonarScanner's [GitLab integration](https://docs.sonarqube.org/latest/analysis/gitlab-integration), that is able to auto-detect whether to launch Branch Analysis or Merge Request Analysis
+This template relies on SonarScanner's [GitLab integration](https://docs.sonarsource.com/sonarqube/latest/devops-platform-integration/gitlab-integration/), which is able to auto-detect whether to launch Branch Analysis or Merge Request Analysis
from GitLab's environment variables.
:warning: This feature also depends on your SonarQube server version and license.
@@ -106,6 +131,9 @@ If using Community Edition, you'll have to install the [sonarqube-community-bran
> :information_source: See [Usage](https://to-be-continuous.gitlab.io/doc/usage/#example-3-disable-go-mod-outdated-job)
> for more information about disabling any job that MAY not be required in a project or group.
+Without disabling the job, you can still exclude a particular project by defining a property `<sonar.skip>true</sonar.skip>` in the pom.xml of the project or module you want to exclude.
+
+
### `mvn-dependency-check` job
This job enables a manual [Dependency-Check](https://jeremylong.github.io/DependencyCheck/dependency-check-maven/configuration.html)
@@ -448,4 +476,3 @@ include:
variables:
```
-
--
GitLab