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 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 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 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 following sections describe how to do this.

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 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 the pom.xml instead of the sonar-project.properties file.
• In the global settings.xml.

Authentication

sonar.token: This is a personal access token generated in your SonarQube Cloud account at My Account > Security > Generate 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:

...
- name: Build and Analyze
  env:
    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, you do not need to pass the token on the mvn command line.

Server, organization, and project

sonar.host.url: This is the URL of the SonarQube Cloud server. It is needed because the SonarScanner for Maven plugin also works with the on-premise SonarQube Server 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 SonarQube Cloud 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 SonarQube Cloud 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:
          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 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:

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

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:

<build>
  <pluginManagement>
    <plugins>
      <plugin>
        <groupId>org.sonarsource.scanner.maven</groupId>
        <artifactId>sonar-maven-plugin</artifactId>
        <version>yourPluginVersion</version>
      </plugin>
    </plugins>
  </pluginManagement>
</build>

When invoking the goal

When invoking the scanner goal, there are two ways to set the plugin version: 

• Using the fully qualified name:

org.sonarsource.scanner.maven:sonar-maven-plugin:<version>:sonar 

• Using the shorthand sonar:sonar instead of the fully qualified name. In this case, the latest plugin version is used:

mvn sonar:sonar

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.

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 below.
• Exclude specific files from the initial scope: see Analysis scope.
• Exclude specific modules from the analysis: see 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 Analysis scope.
• use the scanAll option to extend the initial scope to non-JVM-related files. See 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.scanAll property to True. See Analysis parameters.

Excluding a module from the analysis

To exclude a module from the analysis, you may:

• In the pom.xml of 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 example mvn sonar:sonar -pl !module2

Troubleshooting

If you get a java.lang.OutOfMemoryError

export SONAR_SCANNER_JAVA_OPTS="-Xmx512m"

set SONAR_SCANNER_JAVA_OPTS=-Xmx512m

export MAVEN_OPTS="-Xmx512m"

set MAVEN_OPTS=-Xmx512m