Skip to main content

sbt-sonar

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.

Requirements​

  • sbt 0.13.5+ or 1.0+
  • Scala 2.12/2.13
  • SonarQube server - see my sonar-scala-docker repository, which provides docker-compose recipes and docker images for out-of-the-box SonarQube instance with sonar-scala which brings support for Scala, Scoverage (code coverage metrics), Scalastyle and Scapegoat (static code analysis). Also read the Getting Started guide.
    Alternatively, see the instructions for manual installation here.

Installation​

To install this plugin in your project, add the following to your ./project/plugins.sbt file:

addSbtPlugin("com.sonar-scala" % "sbt-sonar" % "2.3.0")

Usage​

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 in the sonarProperties settings key in sbt, which already comes with the following set of predefined properties:

  • sonar.projectName - your project name defined in the name sbt 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 Compile defined by sbt)
  • sonar.tests - default Scala tests directory relative to the root of your project (usually src/test/scala, uses the value of scalaSource in Test defined by sbt)
  • sonar.scala.version - defines the version of Scala used in your project (i.e. scalaVersion)
  • sonar.scala.scoverage.reportPath - relative path to the scoverage report (e.g. target/scala-2.12/scoverage-report/scoverage.xml)
  • sonar.scala.scapegoat.reportPath - relative path to the scapegoat report (e.g. target/scala-2.12/scapegoat-report/scapegoat.xml)

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 ++= operator, e.g.:

import sbtsonar.SonarPlugin.autoImport.sonarProperties

sonarProperties ++= Map(
  "sonar.modules" -> "module1,module2",
  "module1.sonar.projectName" -> "Module 1",
  "module2.sonar.projectName" -> "Module 2"
)

To overwrite the entire config provided by default, use the := operator, e.g.:

import sbtsonar.SonarPlugin.autoImport.sonarProperties

sonarProperties := Map(
  "sonar.host.url" -> "https://your-sonarqube-server.com",
  "sonar.projectName" -> "Project Name",
  "sonar.projectKey" -> "project-name",
  "sonar.sources" -> "src/main/scala",
  "sonar.tests" -> "src/test/scala",
  "sonar.junit.reportPaths" -> "target/test-reports",
  "sonar.sourceEncoding" -> "UTF-8",
  "sonar.scala.scoverage.reportPath" -> "target/scala-2.12/scoverage-report/scoverage.xml",
  "sonar.scala.scapegoat.reportPath" -> "target/scala-2.12/scapegoat-report/scapegoat.xml"
)

External config​

To use the external sonar-project.properties file instead, you can set the sonarUseExternalConfig to true and you can skip entirely setting the sonarProperties value, e.g.:

import sbtsonar.SonarPlugin.autoImport.sonarUseExternalConfig

sonarUseExternalConfig := true

Execute SonarQube scan​

To run SonarQube analysis, execute the sonarScan sbt task in your project. Depending on the configuration option you have chosen, the plugin will update the 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 sonarProperties via system properties (java options) when you execute sonarScan command, e.g.:

sbt -Dsonar.projectName=MyProjectName sonarScan

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.:

sbt -Dsonar.host.url=https://your-sonarqube-server.com sonarScan

By default this property is set to http://localhost:9000.

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.

sbt-release​

This plugin can be also easily used with sbt-release by wrapping the sonarScan task in a releaseStepTask in the following way:

import sbtsonar.SonarPlugin.autoImport.sonarScan

releaseProcess := Seq[ReleaseStep](
  releaseStepCommand("coverageOn"),
  releaseStepTask(test),
  releaseStepCommand("coverageOff"),
  releaseStepTask(coverageReport),
  releaseStepTask(scapegoat),
  releaseStepTask(sonarScan),
)

Fallback mode​

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 sonar-scanner 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 sonarScanner.home system 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 true, e.g.:

import sbtsonar.SonarPlugin.autoImport.sonarUseSonarScannerCli

sonarUseSonarScannerCli := true

Examples​

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.

Changelog​

  • 2.3.0 (02.05.2021) - Automatically set sonar.projectBaseDir property for the scanned project (#177).
  • 2.2.0 (05.07.2020) - Improve compatibility with SonarScala 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 sonarExpectSonarQubeCommunityPlugin setting is set to true by default. If you're targeting the SonarScala plugin, toggling this setting to false changes the default Scoverage and Scapegoat property names, i.e.:
    • sonar.scala.scoverage.reportPath changes to sonar.scala.coverage.reportPaths
    • sonar.scala.scapegoat.reportPath changes to sonar.scala.scapegoat.reportPaths
  • 2.1.1 (25.04.2020) - Fix missing sonar.projectVersion property (#104).
  • 2.1.0 (16.10.2019) - Allow to use SONAR_HOST_URL environment variable to define SonarQube instance URL instead of the sonar.host.url system property. If both values are present, the sonar.host.url system 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.url property explicitly before running the sonarScan task (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 sonarUseSonarScannerCli setting to true (see the Fallback mode section for more details).
  • 1.7.0 (06.06.2019) - Renamed deprecated sonar.scoverage.reportPath property to sonar.scala.scoverage.reportPath (#30).
  • 1.6.0 (31.12.2018) - Set automatically the sonar.tests property (#25).
  • 1.5.0 (14.09.2018) - Allow sbt-sonar to run on Windows (#16).
  • 1.4.0 (14.09.2018) - Set automatically the sonar.scala.version property (#13).
  • 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/bin for lookup of the sonar-scanner executable (#4).
  • 1.1.0 (19.01.2018) - Search for sonar-scanner home directory in system properties (sonarScanner.home) if SONAR_SCANNER_HOME environmental 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 sonarProperties config; added unit and sbt tests.
  • 0.3.1 (03.01.2017) - Updated the scope of scalaSource setting key to resolve scoping ambiguity with some other plugins.
  • 0.3.0 (02.01.2017) - Defined a set of default project settings in the sonarProperties config key.
  • 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! 🎉