SonarScanner for Maven
The SonarScanner for Maven is a Maven plugin that allows you to execute SonarQube Cloud code analysis via a regular Maven goal.
As a Maven goal, the SonarScanner for Maven is available anywhere Maven is available (locally, in CI services, etc.), without the need to manually download, set up, and maintain a separate installation.
Additionally, because the Maven build process already has much of the information needed for SonarQube Cloud to successfully analyze a project, this information is automatically available to the scanner, reducing the amount of manual configuration needed.
Prerequisites
Maven 3.2.5+
Java 21 or later, Java 17 has been deprecated. See Java runtime environment (JRE) for more details.
Java 11 or later with JRE auto-provisioning
See also the General requirements for your scanner environment page.
A simple example
In the simplest case, you could perform the analysis manually by invoking the Maven goal, while providing the essential parameters. See the example below.
mvn clean verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar \
-Dsonar.token=<your personal access token> \
-Dsonar.region=us \
-Dsonar.organization=<your organization key> \
-Dsonar.projectKey=<your project key>Usually, you would integrate the mvn invocation into your build pipeline, to be run on each commit to your repository. The following sections describe how to do this.
Configuration
While the SonarScanner for Maven automatically detects much of the information needed for code analysis, some manual configuration is required. At a minimum, you need to supply the parameters used to authenticate and connect to the instance, and identify the project.
In general, any of these parameters can be configured just like any other maven property (in order of override priority):
On the
mvncommand line where the scanner goal is invoked, using the-Dargument prefix.In the
pom.xmlfile of the project. Unlike the plain-vanilla SonarScanner CLI, the SonarScanner for Maven uses thepom.xmlinstead of thesonar-project.propertiesfile.In the global
settings.xml.
For more information, see Configuration overview.
Authentication
sonar.token: This is a personal access token generated in your SonarQube Cloud account at My account > Access Tokens > Personal Tokens. It allows the scanner to authenticate to SonarQube Cloud. This is usually set via the SONAR_TOKEN environment variable.
For example, in the GitHub Actions CI environment, you would configure a GitHub Secret called SONAR_TOKEN with the access token as its value. Then you might have something like the following in your .github/workflows/build.yml:
The SonarScanner for Maven automatically picks up the value directly from the environment variable. If you use an environment variable, you do not need to pass the token on the mvn command line.
Server connection and project identification
The parameters you need to set up the connection to the server depend on your situation. For more information, see Server connection.
The properties sonar.organization and sonar.projectKey are used to identify the project. For more information, see Project identification.
These parameters are usually set on the command line of the mvn command invoked during your build in your CI environment. For example, in the GitHub Actions CI environment, you might have the following in your .github/workflows/build.yml.
Optional parameters
Additional parameters beyond the required ones can also be set, either
in the SonarQube Cloud UI,
in your project
pom.xml,or on the command line, as appropriate.
If set on the command line they are simply appended to the mvn command using additional -D argument prefixes.
If set in the pom.xml they are included as part of the project properties. For example:
See the Analysis parameters page for an overview of available parameters.
Invoking the goal
When invoking the SonarScanner goal it is recommended that you do it as part of a single maven command in line with the other goals needed for the build. For example:
where the org.sonarsource.scanner.maven:sonar-maven-plugin:sonar goal follows the verify goal.
This is in contrast to invoking org.sonarsource.scanner.maven:sonar-maven-plugin:sonar in a dedicated mvn invocation. For example:
The advantage with the first technique is that the SonarScanner has access to the full build context and can therefore make a more thorough analysis. For this reason, the first technique is preferred.
Setting the plugin version
In the pom.xml file
We recommend locking down versions of Maven plugins in the pom.xml file of the project:
When invoking the goal
When invoking the scanner goal, there are two ways to set the plugin version:
Using the fully qualified name:
Using the shorthand
org.sonarsource.scanner.maven:sonar-maven-plugin:sonarinstead of the fully qualified name. In this case, the latest plugin version is used:
As of version 5.0 of the scanner, the analysis runs on a provided JDK21 by default. If you're working with a different Java version for your project, there might be inconsistencies between the Java API your project uses and the ones provided during the analysis. Specifying the correct JDK version ensures that you're running the analysis with the correct Java version. See Project-specific JDK article for more information.
Code coverage
To get coverage information, you will need to generate the coverage report before the analysis and specify the location of the resulting report in an analysis parameter. See the Test coverage page for details.
Adjusting the analysis scope
The analysis scope of a project determines the source and test files to be analyzed.
An initial analysis scope is set by default. With the SonarScanner for Maven, the initial analysis scope is:
For source files: all the files stored under
src/main/java(in the root or module directories).For test files: all the files stored under
src/test/java(in the root or module directories).
To adjust the analysis scope, you can:
Adjust the initial scope. See Adjusting the initial scope below.
Exclude specific files from the initial scope. See the Analysis scope pages.
Exclude specific modules from the analysis. See Excluding a module from the analysis below.
Adjusting the initial scope
The initial scope is set through the sonar.sources property (for source files) and the sonar.tests property (for test files). See Analysis parameters for more information.
To adjust the initial scope, you have two options:
override these properties by setting them explicitly in your build like any other relevant maven property. See the Setting initial scope page.
use the scanAll option to extend the initial scope to non-JVM-related files. See Using the scanAll option to include non-JVM-related files below.
Using the scanAll option to include non-JVM-related files
You may want to analyze not only the JVM main files but also files related to configuration, infrastructure, etc. An easy way to do that is to enable the scanAll option (By default, this option is disabled.).
If the scanAll option is enabled then the initial analysis scope of source files will be:
The files stored in
src/main/java.The non-JVM-related files stored in the root directory of your project.
To enable the scanAll option:
Set the
sonar.maven.scanAllproperty toTrue. See the Analysis parameters page.
Excluding a module from the analysis
To exclude a module from the analysis, you may:
In the
pom.xmlof the module you want to exclude, define the<sonar.skip>true</sonar.skip>property.Use build profiles to exclude some modules (like for integration tests).
Use Advanced Reactor Options (such as
-pl). For examplemvn org.sonarsource.scanner.maven:sonar-maven-plugin:sonar -pl !module2
Analysis property defaults
The SonarScanner for Maven uses information contained in your project's pom.xml to provide smart defaults for most of the standard analysis parameters, as listed below. Note that additional defaults are provided for Java and Groovy projects. For more information about the listed properties, see Parameters not settable in the UI.
Maven defaults for standard SonarQube Cloud properties
Property
Maven default
sonar.projectKey
${project.groupId}:${project.artifactId}
sonar.projectName
${project.name}
sonar.projectDescription
${project.description}
sonar.projectVersion
${project.version}
sonar.projectBaseDir
${project.basedir}
sonar.sourceEncoding
${project.build.sourceEncoding}
sonar.working.directory
${project.build.directory}/sonar
sonar.links.homepage
${project.url}
sonar.links.ci
${project.ciManagement.url}
sonar.links.issue
${project.issueManagement.url}
sonar.links.scm
${project.scm.url}
sonar.links.scm_dev
${project.scm.developerConnection}
Additional defaults for Java projects
Property
Maven default
sonar.java.source
${maven.compiler.release} (falls back to ${maven.compiler.source} if not set)
sonar.java.target
${maven.compiler.release} (falls back to ${maven.compiler.target} if not set)
sonar.java.enablePreview
${maven.compiler.enablePreview} (if set)
sonar.java.jdkHome
${maven.compiler.jdkHome} (if set)
sonar.sources
${project.compileSourceRoots}, plus the module's pom.xml file and a .github directory if present (filtered to only include existing, non-nested paths)
sonar.tests
${project.testCompileSourceRoots} (filtered to only include existing, non-nested paths)
sonar.java.binaries
${project.build.outputDirectory} (if the directory exists)
sonar.java.libraries
Resolved compile classpath elements (filtered to only include existing files)
sonar.java.test.binaries
${project.build.testOutputDirectory} (if the directory exists)
sonar.java.test.libraries
Resolved test classpath elements (filtered to only include existing files)
sonar.junit.reportPaths
The Maven Surefire plugin's reportsDirectory (default ${project.build.directory}/surefire-reports), if it exists
Additional default for Groovy projects
Property
Maven default
sonar.groovy.binaries
Same value as sonar.java.binaries
Troubleshooting
If you get a java.lang.OutOfMemoryError
Related pages
Last updated
Was this helpful?