SonarQube Properties and Parameters

Parameters to configure project analysis can be set in multiple places. Here is the hierarchy of parameters:


Note that only parameters set through the UI are stored in the database.

For example, if you override the sonar.exclusions parameter via command line for a specific project, it will not be stored in the database. Local analyses in Eclipse, for example, would still be executed with the exclusions defined in the UI and therefore stored in the DB.

Setting properties from the Command Line

SonarQube properties can also be set from the command line, by setting a system property named exactly like the SonarQube property in question. This can be useful when dealing with sensitive information (e.g. credentials), environment information, or for ad-hoc configuration.

gradle sonarqube -Dsonar.host.url=http://sonar.mycompany.com -Dsonar.verbose=true

A SonarQube property value set via a system property overrides any value set in a build script (for the same property). When analyzing a project hierarchy, values set via system properties apply to the root project of the analyzed hierarchy. Each system property starting with ""sonar." will be taken into account.

sonar-project.properties

Create a configuration file in the root directory of the project: sonar-project.properties

sonar-project.properties
# must be unique in a given SonarQube instance
sonar.projectKey=my:project
# this is the name and version displayed in the SonarQube UI. Was mandatory prior to SonarQube 6.1.
sonar.projectName=My project
sonar.projectVersion=1.0
 
# Path is relative to the sonar-project.properties file. Replace "\" by "/" on Windows.
# This property is optional if sonar.modules is set. 
sonar.sources=.
 
# Encoding of the source code. Default is default system encoding
#sonar.sourceEncoding=UTF-8

Alternatives to sonar-project.properties

If a sonar-project.properties file cannot be created in the root directory of the project, there are several alternatives:

 

Alternate Analysis Directory

If the files to be analyzed are not in the directory where the analysis starts from, use the sonar.projectBaseDir property to move analysis to a different directory. E.G. analysis begins from jenkins/jobs/myjob/workspace but the files to be analyzed are in ftpdrop/cobol/project1.

sonar-project.properties
sonar.projectBaseDir=/home/ftpdrop/cobol/project1
sonar.sources=src
sonar.cobol.copy.directories=/copy

Multi-module Project Structure

If your project is a Maven project, you have nothing further to do to enable multi-module analysis. Simply execute mvn sonar:sonar from your project's root directory. If your multi-module project is not a Maven project, read on:

There are two ways to define a multi-module structure in SonarQube:

Method - 1

Method - 2

 

Gradle defaults for standard SonarQube properties

 

Property Gradle default 
sonar.projectKey
 [$project.group:]$project.name for root module
<root module key>:<module path> for submodules 		 
sonar.projectName
 project.name 
sonar.projectDescription
 project.description 
sonar.projectVersion
 project.version 
sonar.projectBaseDir
 project.projectDir 
sonar.working.directory
 “$project.buildDir/sonar”
Notice that additional defaults are provided for projects that have the java-base or java plugin applied:

Mandatory Parameters

Server

Key

Description

Default value
sonar.host.url Server URL http://localhost:9000

Project Configuration

Key

Description

Default value
sonar.projectKey

The project key that is unique for each project. 
Allowed characters are: letters, numbers, '-', '_', '.' and ':', with at least one non-digit. 

When using Maven, it is automatically set to <groupId>:<artifactId>.

  
sonar.sources

Comma-separated paths to directories containing source files.
Compatible with Maven. If not set, the source code is retrieved from the default Maven source code location. 

  

Optional Parameters

Project identity

Key

Description

Default value
sonar.projectName

Name of the project that will be displayed on the web interface.
Set through <name> when using Maven.
  • If there is no name defined yet, use the project key
  • If there is already a name in the DB, don't overwrite;
sonar.projectVersion
The project version.
Set through <version> when using Maven.
 "not provided"

Authentication

If Anyone does not have permission to perform analyses, you'll need to supply the credentials of a user with Execute Analysis permission for the analysis to run under.

Key
Description
Default value
sonar.login The login or authentication token of a SonarQube user with Execute Analysis permission.  
sonar.password The password that goes with the sonar.login username. This should be left blank if an authentication token is being used.  

Web Services

Key
Description
Default value
sonar.ws.timeout Maximum time to wait for the response of a Web Service call (in seconds). Modifying this value from the default is useful only when you're experiencing timeouts during analysis while waiting for the server to respond to Web Service calls.  60

Project Configuration

Key

Description

Default value
sonar.projectDescription

The project description.
Not compatible with Maven, which uses the <description> attribute.

  
sonar.links.homepage Project home page
Not compatible with Maven, which uses the <url> attribute.		  

sonar.links.ci

 Continuous integration 
Not compatible with Maven, which uses the <ciManagement><url> attribute.		  
sonar.links.issue Issue tracker
Not compatible with Maven, which uses the <issueManagement><url> attribute.		  
sonar.links.scm Project sources
Not compatible with Maven, which uses the <scm><url> attribute.		  
sonar.links.scm_dev Developer connection
Not compatible with Maven, which uses the <scm><developerConnection> attribute.		  
sonar.tests

Comma-separated paths to directories containing tests.
Not compatible with Maven, which retrieves test from the default location for Java Maven projects.  

  

sonar.language

Set the language of the source code to analyze. Browse the Plugin Library page to get the list of all available languages. If not set, a multi-language analysis will be triggered.

 

sonar.sourceEncoding

Set the source file encoding.

Encoding of source files. Example of values: UTF-8, MacRoman, Shift_JIS. This property can be replaced by the standard property project.build.sourceEncoding in Maven projects.

The list of available encodings depends on your JVM. See http://docs.oracle.com/javase/1.5.0/docs/guide/intl/encoding.doc.html (column : Canonical Name for java.nio API)

System encoding

sonar.projectDate

Assign a date to the analysis.

Note: This parameter is applicable to a few, special use cases, rather than being an "every day" parameter:

  • When analyzing a new project, you may want to retroactively create some history for the project in order to get some information on quality trends over the last few versions.
  • When moving from one database engine to another, it is highly recommended (even mandatory) to start from a fresh new database schema. In doing so, you will lose the entire history for all your projects. Which is why you may want to feed the new SonarQube database with some historical data.

To answer those use cases, you can use the sonar.projectDate property. The format is yyyy-MM-dd, for example: 2010-12-01.

The process is the following:

  • Retrieve the oldest version of your application's source that you wish to populate into the history (from a specific tag, whatever).
  • Run a SonarQube analysis on this project by setting the sonar.projectDate property. Example: sonar-scanner -Dsonar.projectDate=2010-12-01
  • Retrieve the next version of the source code of your application, update the sonar.projectDate property, and run another analysis. And so on for all the versions of your application you're interested in.
Since you cannot perform an analysis dated prior to the most recent one in the database, you must analyze your versions in chronological order, oldest first.
(warning)Note: You may need to adjust your housekeeping settings if you wish to create a long-running history.

Current date

 sonar.branch

Manage SCM branches. (warning) Two branches of the same project are considered to be different projects in SonarQube. As a consequence issues found in a project A in a branch B1 are not linked to issues found for this project A in a branch B2. Currently, there is no way to resolve automatically issues of B2 when they are resolved in B1 as again A-B1 & A-B2 are considered as separated project.

If you are a user of Developer Cockpit, please see "Limitation" section in the Developer Cockpit Installation and Usage

 

sonar.profile

This property is deprecated since SQ 4.5 LTS (see SONAR-5370 - Deprecate usage of "sonar.profile" as an analysis parameter CLOSED ) and should not be used.

Default profile for the given language

 

sonar.projectBaseDir

Use this property when you need analysis to take place in a directory other than the one from which it starts. E.G. analysis begins from jenkins/jobs/myjob/workspace but the files to be analyzed are in ftpdrop/cobol/project1. The path may be relative or absolute.

Specify not the the source directory, but some parent of the source directory. The value specified here becomes the new "analysis directory", and other paths are then specified as though the analysis were starting from the new sonar.projectBaseDir.

Note that the analysis process will need write permissions in this directory; it is where the sonar.working.directory will be created.

  
 sonar.working.directory

Set the working directory for an analysis triggered with the SonarQube Scanner or the SonarQube Ant Task (versions greater than 2.0).

Path must be relative and unique for each project.

Beware: the specified folder is deleted before each analysis.

 .sonar 
sonar.scm.provider
 This property can be used to explicitly tell SonarQube which SCM plugin should be used to grab SCM data on the project (in case auto-detection does not work). The value of this property is always lowercase and depends on the plugin (ex. "tfvc" for the TFVC plugin). Check the documentation page of each plugin to know more.  
sonar.scm.forceReloadAll By default, blame information is only retrieved for changed files. Set this property to true to load blame information for all files. This can be useful is you feel that some SCM data is outdated but SonarQube does not get the latest information from the SCM engine. false

Exclusions / Inclusions

See Narrowing the Focus to:

Key
Description
Default value
sonar.inclusions Comma-delimited list of file path patterns to be included in analysis. When set, only files matching the paths set here will be included in analysis.  
sonar.exclusions Comma-delimited list of file path patterns to be excluded from analysis.  
sonar.coverage.exclusions Comma-delimited list of file path patterns to be excluded from coverage calculations  
sonar.test.exclusions Comma-delimited list of test file path patterns to be excluded from analysis.  
sonar.test.inclusions Comma-delimited list of test file path patterns to be included in analysis. When set, onlytest files matching the paths set here will be included in analysis.  
sonar.issue.ignore.allfile Files containing text matching this regular expression will be ignored by analysis.   
sonar.import_unknown_files
 If set to true, all files are imported - with respect to inclusions and exclusions, even if there is no matching language plugin installed. 
false
sonar.cpd.exclusions Comma-delimited list of file path patterns to be excluded from duplication detection  

Duplications

Key Description

Default value
sonar.cpd.exclusions (see the Exclusions/Inclusions section)  
sonar.cpd.${language}.minimumtokens A piece of code is considered duplicated as soon as there are at least 100 duplicated tokens in a row (overide with sonar.cpd.${language}.minimumTokens) spread on at least 10 lines of code (override with sonar.cpd.${language}.minimumLines). For Java projects, a piece of code is considered as duplicated when there is a series of at least 10 statements in a row, regardless of the number of tokens and lines. This threshold cannot be overridden.  100
sonar.cpd.${language}.minimumLines 10

Analysis Logging

Key
Description
Default value
 
sonar.log.level

Control the quantity / level of logs produced during an analysis.

DEBUG: 
Display INFO logs + more details at DEBUG level.
Similar to sonar.verbose=true

TRACE: 
Display DEBUG logs + the timings of all ElasticSearch queries and Web API calls executed by the SonarQube Scanner.

 
INFO
sonar.verbose

Add more detail to both client and server-side analysis logs.

  • Activates DEBUG mode for the scanner. This is a shortcut of sonar.log.level=DEBUG.
  • Adds client-side environment variables and system properties to server-side log of analysis report processing. 
    NOTE There is the potential for this setting to expose sensitive information such as passwords if they are stored as server-side environment variables.
 false
sonar.showProfiling

Display logs to see where the analyzer spends time.

This parameter is generating a file containing these timing infos in

<workingDir>/profiling/<moduleKey>-profiler.xml where <workingDir> is:
  • .sonar/profiling/ when analysis is run with Sonar Scanner
  • target/sonar/profiling/ when Maven is used 
 false
sonar.scanner.dumpToFile Outputs to the specified file the full list of properties passed to the scanner API as a means to debug analysis.  

Parameters specific to Integration

Those parameters are listed here for completeness of this documentation page - but regular users should not have to worry about them because they mainly target integration use cases.

Key

Description
sonar.analysis.mode

This parameter is set to preview as part of PR analysis.

Reference

https://docs.sonarqube.org/display/SCAN/Advanced+SonarQube+Scanner+Usage
https://docs.sonarqube.org/display/SONAR/Analysis+Parameters


  Call us on +91 700 483 5930   |   +91 700 483 5706     Contact@DevopsSchool.com