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 ofscalaSource 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 ofscalaSource 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
sonar.host.url
environment 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.:
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 thesonarExpectSonarQubeCommunityPlugin
setting is set totrue
by default. If you're targeting the SonarScala plugin, toggling this setting tofalse
changes the default Scoverage and Scapegoat property names, i.e.:sonar.scala.scoverage.reportPath
changes tosonar.scala.coverage.reportPaths
sonar.scala.scapegoat.reportPath
changes tosonar.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 thesonar.host.url
system property. If both values are present, thesonar.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 thesonarScan
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 thesonarUseSonarScannerCli
setting totrue
(see the Fallback mode section for more details). - 1.7.0 (06.06.2019) - Renamed deprecated
sonar.scoverage.reportPath
property tosonar.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
) ifSONAR_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! 🎉