SonarQube Build Breaker Plugin

Compatibility

SonarQube Version	Plugin Version(s)
4.5 (LTS)	1.1
5.0	1.1
5.1	1.1
5.2	Not compatibile due to limitations with SonarQube platform
5.3	2.0, 2.1
5.4	2.0, 2.1
5.5	2.1
5.6 (LTS)	2.1

Download and Installation

1. Download the appropriate sonar-build-breaker-plugin-${version}.jar file from the releases page, based on the compatibility chart
2. Copy the plugin into /path/to/sonarqube/extensions/plugins/
3. Remove older versions of the plugin from /path/to/sonarqube/extensions/plugins/, if present
4. Restart SonarQube

Description

This plugin will mark the build failed if the project fails its quality gate or uses a forbidden configuration. These checks happen after analysis has been submitted to the server, so it does not prevent a new analysis from showing up in SonarQube.

Upon uploading the analysis information, the plugin follows the below workflow to check the quality gate:

1. Search ${sonar.working.directory}/report-task.txt for ceTaskId, the server-side Compute Engine (CE) task associated with the current analysis
2. Call the ${sonar.host.url}/api/ce/task?id=${ceTaskId} web service to retrieve analysisId
3. If the CE Task Status is PENDING or IN_PROGRESS, wait sonar.buildbreaker.queryInterval and repeat step 2
4. If the CE Task Status is SUCCESS, save the analysisId and proceed to step 3
5. If the CE Task Status is FAILED or none of the above, break the build
6. If step 2 has been attempted sonar.buildbreaker.queryMaxAttempts times, break the build
7. Call the ${sonar.host.url}/api/qualitygates/project_status?analysisId=${analysisId} web service to check the status of the quality gate
8. If the quality gate status is OK, allow the build to pass
9. If the quality gate status is WARN, allow the build to pass and log the current warnings
10. If the quality gate status is ERROR, break the build and log the current warnings and errors

The build "break" is accomplished by throwing an exception, making the analysis return with a non-zero status code. This allows you to benefit from the notifications built into CI engines or use your own custom notifications that check the exit status.

Usage

Quality Gate Build Breaker

1. Associate a quality gate to your project
2. Optional: Tune sonar.buildbreaker.queryMaxAttempts and/or sonar.buildbreaker.queryInterval
3. Check the duration of previous CE (background) tasks for your project, from submission until completion
4. Ensure sonar.buildbreaker.queryMaxAttempts * sonar.buildbreaker.queryInterval is longer than the above duration (with default values, total wait time is ~5 minutes)
5. For small projects, a faster interval may be desired so your build times are not longer than necessary
6. For very large projects or servers with a busy CE queue, more attempts or a longer interval may be necessary
7. Run an analysis on your project
8. If analysis fails while waiting for CE to complete, increase either sonar.buildbreaker.queryMaxAttempts, sonar.buildbreaker.queryInterval, or both

Forbidden Configuration Build Breaker

Define the property sonar.buildbreaker.forbiddenConf with comma-separated key=value configurations that will break the build.

For example, if you set the property to sonar.gallio.mode=skip, each analysis on .NET projects executed with Gallio skipped will be marked "broken".

Configuration Parameters

Property	Description	Default value	Example
sonar.buildbreaker.skip	If set to true, the quality gate is not checked. By default the build will break if the project does not pass the quality gate.	false
sonar.buildbreaker.queryMaxAttempts	The maximum number of queries to the API when waiting for report processing. The build will break if this is reached. Total wait time is sonar.buildbreaker.queryMaxAttempts * sonar.buildbreaker.queryInterval.	30
sonar.buildbreaker.queryInterval	The interval (ms) between queries to the API when waiting for report processing. Total wait time is sonar.buildbreaker.queryMaxAttempts * sonar.buildbreaker.queryInterval.	10000
sonar.buildbreaker.forbiddenConf	Comma-separated list of key=value pairs that should break the build.		sonar.gallio.mode=skip