SonarScanner for Maven
The SonarScanner for Maven is a Maven plugin that allows you to execute SonarCloud code analysis via a regular Maven goal.
As a Maven goal, the scanner 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 SonarCloud 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 17 or later
A simple example
In the simplest case, you could perform the analysis manually by invoking the Maven goal, while providing the essential parameters. Something like this:
$ mvn clean verify sonar:sonar \
-Dsonar.token=<your personal access token> \
-Dsonar.host.url=https://sonarcloud.io \
-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 sections that follow describe how best to do this.
Setting the plugin group
In most cases you will want to invoke the scanner goal using the shorthand sonar:sonar
instead of its fully qualified name (org.sonarsource.scanner.maven:sonar-maven-plugin:<version>:sonar
). To ensure that this always works, you should set a plugin group in your Maven global settings.xml
(usually found in ~/.m2/
) like this:
<settings>
...
<pluginGroups>
<pluginGroup>
org.sonarsource.scanner.maven
</pluginGroup>
</pluginGroups>
...
</settings>
Configuration
While the SonarScanner for Maven does automatically detect much of the information needed to perform code analysis, some manual configuration is needed. At the minimum you need to supply the four parameters mentioned above: sonar.token
, sonar.host.url
, sonar.organization
, and sonar.projectKey
.
In general, any of these parameters can be configured just like any other maven property (in order of override priority):
- On the
mvn
command line where the scanner goal is invoked, using the-D
argument prefix. - In the
pom.xml
file of the project. Unlike the plain-vanilla SonarScanner CLI, the SonarScanner for Maven uses thepom.xml
instead of thesonar-project.properties
file. - In the global
settings.xml
.
Authentication
sonar.token
: This is a personal access token generated in your SonarCloud account at My Account > Security > Generate Tokens. It allows the scanner to authenticate to SonarCloud. 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
:
...
- name: Build and Analyze
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
...
The SonarScanner for Maven automatically picks up the value directly from the environment variable. If you use an environment variable, it is not necessary to pass the token on the mvn
command line.
Server, organization, and project
sonar.host.url
: This is the URL of the SonarCloud server. It is needed because the SonarScanner for Maven plugin also works with the on-premise SonarQube product, where this parameter is set to the URL of the locally installed server. In our case, this parameter should always be set to https://sonarcloud.io
.
sonar.organization
: This is the key of the SonarCloud organization where your project resides. It can be found in the top right of the organization overview page and on the information page of your project.
sonar.projectKey
: This is the key of the SonarCloud project itself, that is, the one resulting from importing the repository that you are now configuring. It can be found on the information page of your project.
These three 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
:
- name: Build and analyze
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
run: mvn verify sonar:sonar \
-Dsonar.host.url=https://sonarcloud.io \
-Dsonar.organization=<your organization key> \
-Dsonar.projectKey=<your project key>
Optional parameters
Additional parameters beyond the required ones can also be set, either
- in the SonarCloud 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:
<project>
...
<properties>
<sonar.buildString>...</sonar.buildString>
</properties>
...
</project>
See Analysis Parameters 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:
mvn verify sonar:sonar \
-Dsonar.organization=<your organization key> \
-Dsonar.projectKey=<your project key>
where the sonar:sonar
goal follows the verify
goal.
This is in contrast to invoking sonar:sonar
is a dedicated mvn
invocation. For example:
mvn clean install
mvn sonar:sonar \
-Dsonar.organization=<your organization key> \
-Dsonar.projectKey=<your project key>
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.
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 Test Coverage for details.
Excluding a module
- Define the property
<sonar.skip>true</sonar.skip>
in thepom.xml
of the module you want to exclude. - Use build profiles to exclude some modules (for example, for integration tests).
- Use Advanced Reactor Options (such as
-pl
). For example:mvn verify sonar:sonar -pl !module2
Troubleshooting
If you get a java.lang.OutOfMemoryError
, set the MAVEN_OPTS
environment variable, like this in Unix-based environments:
export MAVEN_OPTS="-Xmx512m"
In Windows environments, avoid the double quotes because they often get misinterpreted:
set MAVEN_OPTS=-Xmx512m