/sonar-quality-gate-maven-plugin

Sonar Quality Gate Maven Plugin

Primary LanguageJavaApache License 2.0Apache-2.0

Sonar Quality Gate Maven Plugin

Maven Central Quality Gate Status Coverage Black Duck Security Risk Maven Build

Check your SonarQube project if it passes its quality gate. If it doesn't, the plugin will fail the maven job.

There a three modes supported:

Mode Description
integrated (recommended) Run in conjunction with sonar-maven-plugin (supports branches and pull requests)
The required information for fetching the data will be read from a sonar-maven-plugin generated file in target
simple Run stand-alone for a simple SonarQube project (no branches)
advanced Run stand-alone for a SonarQube project with branch name or pull request

Prerequisites

  • Java 11
  • SonarQube (depends on mode)
    • integrated: 5.3+
    • simple: 5.4+
    • advanced: 7.7+

Usage

Include the plugin declaration in your pom.xml either in <build><pluginManagement><plugins> for calling it only explicitly on CLI or in <build><plugins> to integrate it automatically in your build.

<plugin>
  <groupId>io.github.r0bb3n</groupId>
  <artifactId>sonar-quality-gate-maven-plugin</artifactId>
  <version>1.1.0</version>
</plugin>

You can also use it without changing your pom.xml by calling it fully qualified on CLI:

mvn io.github.r0bb3n:sonar-quality-gate-maven-plugin:1.1.0:check

Integrated mode

mvn sonar:sonar sonar-quality-gate:check

Simple mode

mvn sonar-quality-gate:check

Ensure that there is no (old) metadata inside target from a former sonar-maven-plugin run (especially target/sonar/report-task.txt) otherwise it will switch automatically to integrated mode.

Advanced mode

mvn sonar-quality-gate:check -Dsonar-quality-gate.branch=develop

Plugin parameters

Parameter Description Used in mode
sonar.host.url sonar host url (aligned to sonar-maven-plugin analysis parameters) all
sonar.login sonar login (username or token) for basic auth (aligned to sonar-maven-plugin analysis parameters)
see also SonarQube - Web API Authentication		 all
sonar.password sonar password for basic auth (aligned to sonar-maven-plugin analysis parameters)
see also SonarQube - Web API Authentication		 all
sonar.projectKey project key used in sonar for this project (aligned to sonar-maven-plugin analysis parameters)
(default: ${project.groupId}:${project.artifactId})		 simple, advanced
sonar-quality-gate.skip skip plugin execution
(default: false)		 all
sonar-quality-gate.failOnMiss fail the execution when the quality gate was not passed (status is not OK)
(default: true)		 all
sonar-quality-gate.branch name of the branch to check the quality gate in sonar advanced
sonar-quality-gate.pullRequest name of the pull request to check the quality gate in sonar advanced
sonar-quality-gate.checkTask.attempts How often try to retrieve the analysis id from the task details in sonar until stopping the job
(default: 10)		 integrated
sonar-quality-gate.checkTask.interval.s How many seconds to wait between two requests when retrieving task details
(default: 5)		 integrated

Internals

Why Java 11?

TL;DR usage of HttpClient (java.net.http.HttpClient)

Thinking about also supporting Java 8 led to the conclusion, that this would require relying on at least one additional dependency (to maintain) for HTTP calls (e.g. Apache HttpClient), which is solved out-of-the-box in Java 11+ by simply using java.net.http.HttpClient. Therefore, I decided to not support Java 8.

Calling SonarQube Web API

Project Status

Get the quality gate status of a project.

Endpoint

api/qualitygates/project_status

URL Parameters

Parameter Supported
projectKey yes
branch yes
pullRequest yes
analysisId yes
projectId no

Documentation

  • on sonarcloud.io Web-API
  • in your SonarQube instance: <sonar.host.url>/web_api/api/qualitygates/project_status

Compute Engine Task (ceTask)

This endpoint is used to retrieve the analysis id of a prior sonar-maven-plugin run.

Endpoint

api/ce/task

URL Parameters

Parameter Supported
id yes
additionalFields no

Documentation

Maven calls

Release

prepare - manage pom.xml and create proper commits and tag and push to remote

mvn -B release:prepare -DdevelopmentVersion=1-SNAPSHOT -DreleaseVersion=<release version> -Dtag=v<release version>

perform - checkout version tag, create binaries and deploy via oss.sonatype.org to Maven Central

mvn -B release:perform

clean - remove backup/work file (useful if you ran prepare but not perform)

mvn -B release:clean

How-To release

  1. Update CHANGELOG.md: add a section for the upcoming version and move all "unpublished" changes to it
  2. Update README.md: replace all occurrences of previous version number with upcoming version
  3. persist: git add CHANGELOG.md README.md && git commit -m "prepare for release: update CHANGELOG.md/README.md" && git push
  4. create release in git repo: mvn -B release:prepare -DdevelopmentVersion=1-SNAPSHOT -DreleaseVersion=1.1.0 -Dtag=v1.1.0
  5. create and publish binaries: mvn -B release:perform -DreleaseProfiles=build-for-release
  6. Create new release on GitHub (here)
    • choose tag: v1.1.0
    • set title: 1.1.0
    • copy the CHANGELOG.md content of the released version
    • upload the files ./target/checkout/target/*.(pom|jar|asc)
  7. publish staging repository of oss nexus repository (login required) to maven central (overview doc / detailed doc)
    1. check content of the staging repo
    2. select staging repo
    3. "Close" repo
    4. evaluation is now running, see repo tab "Activity"
    5. "Refresh" repo view
    6. "Release" repo
    7. copying is ongoing, see repo tab "Activity"
    8. "Refresh" repo view, staging repo will disappear after successful copy process
    9. verify that files are now available on the public release repo: GAV search