sbt-sonar is an sbt plugin, which provides an easy way to execute SonarQube analysis for Scala projects. It uses an embedded sonar-scanner API under the hood, which allows you to run SonarQube scan without the need to have the sonar-scanner executable installed in your environment.
- sbt 0.13.5+ or 1.0+
- Scala 2.11/2.12
- SonarQube server - see my
repository, which provides docker-compose recipes and docker images for
out-of-the-box SonarQube instance with sonar-scala which brings support for
coverage metrics), Scalastyle and
Scapegoat (static code analysis).
Also read the Getting Started guide.
Alternatively, see the instructions for manual installation here.
To install this plugin in your project, add the following to your
addSbtPlugin("com.sonar-scala" % "sbt-sonar" % "2.3.0")
You can define your project properties either in the external config file
sonar-project.properties, which should be located in the root directory of
your project as explained in
SonarQube Scanner guide
or directly in sbt. By default, the plugin expects the properties to be defined
sonarProperties settings key in sbt, which already comes with the
following set of predefined properties:
- sonar.projectName - your project name defined in the
namesbt setting key
- sonar.projectKey - your project name transformed into a lowercase and dash-separated value
- sonar.sourceEncoding - UTF-8
- sonar.sources - default Scala source directory relative to the root of
your project (usually
src/main/scala, uses the value of
scalaSource in Compiledefined by sbt)
- sonar.tests - default Scala tests directory relative to the root of your
src/test/scala, uses the value of
scalaSource in Testdefined by sbt)
- sonar.scala.version - defines the version of Scala used in your project
- sonar.scala.scoverage.reportPath - relative path to the scoverage report
- sonar.scala.scapegoat.reportPath - relative path to the scapegoat report
Usually, the default settings are sufficient for majority of the projects and you rarely need to change any of them, unless your project is set-up in an unconventional way or contains multiple modules.
To add more properties to the existing config or to overwrite any of the
existing ones e.g. to set up a multi-module project, you can use the
To overwrite the entire config provided by default, use the
:= operator, e.g.:
To use the external
sonar-project.properties file instead, you can set the
true and you can skip entirely setting the
sonarProperties value, e.g.:
To run SonarQube analysis, execute the
sonarScan sbt task in your project.
Depending on the configuration option you have chosen, the plugin will update
sonar.projectVersion property to your current project version either in
sonar-project.properties file or in the
sonarProperties in sbt config and it
will run the SonarQube scan printing the progress to sbt console.
Also, you can overwrite/set
via system properties (java options) when you execute
sonarScan command, e.g.:
sonar.host.urlenvironment property before you execute the analysis.
You can do that either by adding it to the
sonarProperties settings in sbt (as
shown in the examples above), or you can set it via a system property, e.g.:
By default this property is set to
sbt-sonar can also read the URL of your SonarQube instance from the
SONAR_HOST_URL environment variable instead of system properties. If both
values are present, the
sonar.host.url system property takes precedence over
the environment variable.
This plugin can be also easily used with
sbt-release by wrapping the
task in a
releaseStepTask in the following way:
It is possible to make the plugin call through to a standalone sonar-scanner executable, if that's what you prefer, for any reasons. This was the default behaviour before version 2.0 and in case you experience any issues with 2.x, you can fall back to using the standalone mode.
In order to do that, you need to have the
installed on your CI server or locally, if you intend to run the analysis on
your machine. You also need to make sure you have defined the
SONAR_SCANNER_HOME environmental variable, or
property, and updated the global settings in
$SONAR_SCANNER_HOME/conf/sonar-scanner.properties to point to your SonarQube
instance (you can also do that by setting the
sonar.host.url via system
properties, as shown above).
To enable the fallback mode set the
sonarUseSonarScannerCli seting to
Please see the tests directory for some example projects. You can find there examples of projects using sbt 0.13 and 1.0, Scala 2.11, 2.12, a multi-module project and a project using an external properties file.
- 2.3.0 (02.05.2021) - Automatically set
sonar.projectBaseDirproperty for the scanned project (#177).
- 2.2.0 (05.07.2020) - Improve compatibility with
plugin (#117). This
release adds a new setting key (
sonarExpectSonarQubeCommunityPlugin), which allows toggling compatibility between sonar-scala and SonarScala plugins. This change is backwards compatible and the
sonarExpectSonarQubeCommunityPluginsetting is set to
trueby default. If you're targeting the SonarScala plugin, toggling this setting to
falsechanges the default Scoverage and Scapegoat property names, i.e.:
- 2.1.1 (25.04.2020) - Fix missing sonar.projectVersion property (#104).
- 2.1.0 (16.10.2019) - Allow to use
SONAR_HOST_URLenvironment variable to define SonarQube instance URL instead of the
sonar.host.urlsystem property. If both values are present, the
sonar.host.urlsystem property takes precedence over the environment variable. (sonar-scanner-api#69)
- 2.0.0 (17.06.2019) - Use an embedded sonar-scanner
(#34) 🎊 This
version removes the dependency on having the standalone sonar-scanner-cli
installed. To upgrade from 1.x please define the
sonar.host.urlproperty explicitly before running the
sonarScantask (see the Execute SonarQube section for more details). If you want to fallback to the default behaviour from 1.x, which makes the plugin call through to the standalone sonar-scanner, you can set the
true(see the Fallback mode section for more details).
- 1.7.0 (06.06.2019) - Renamed deprecated
- 1.6.0 (31.12.2018) - Set automatically the
- 1.5.0 (14.09.2018) - Allow sbt-sonar to run on Windows (#16).
- 1.4.0 (14.09.2018) - Set automatically the
- 1.3.0 (06.02.2018) - Allow to set sonar properties via system properties (#7).
- 1.2.0 (31.01.2018) - Use
SONAR_SCANNER_HOME/binfor lookup of the sonar-scanner executable (#4).
- 1.1.0 (19.01.2018) - Search for
sonar-scannerhome directory in system properties (
SONAR_SCANNER_HOMEenvironmental variable is not defined (#1).
- 1.0.0 (06.11.2017) - Support for sbt 1.0 💪 default scoverage and
scapegoat report paths added automatically to the
sonarPropertiesconfig; added unit and sbt tests.
- 0.3.1 (03.01.2017) - Updated the scope of
scalaSourcesetting key to resolve scoping ambiguity with some other plugins.
- 0.3.0 (02.01.2017) - Defined a set of default project settings in the
- 0.2.0 (22.12.2016) - Added the ability to define sonar project properties directly in sbt.
- 0.1.0 (12.12.2016) - First release of the plugin! 🎉