Analysis parameters

Project analysis settings can be configured in multiple places. Each plugin and language analyzer adds its own properties which can be defined in the SonarQube UI; these properties can also be defined as analysis parameters, however, the descriptions of those properties and the best place to set them is in the UI when possible. Only parameters set through the UI are reusable for subsequent analysis and there is a structure to the way parameters are read by the scanner.

Here is the hierarchy in order of precedence:

1. Global properties: Apply to all projects. Defined in the UI in Administration > Configuration > General Settings
2. Project properties: Apply to one project only. At project level, defined in the UI in Project Settings > General Settings
3. Project analysis parameters: Defined in a project analysis configuration file or scanner configuration file
4. Analysis / Command line parameters: Defined when launching an analysis with -D on the command line

Note that only parameters set through the UI are stored in the database. For example, if you override the sonar.exclusions parameter via the command line for a specific project, it will not be stored in the database. Subsequent analyses, or analyses in SonarLint with connected mode, would still be executed with the exclusions defined in the UI and therefore stored in the DB.

Most of the property keys shown in the interface at both global and project levels can also be set as analysis parameters, but the parameters listed below can only be set at analysis time.

For language-specific parameters related to test coverage and execution, see Test coverage. For language-specific parameters related to external issue reports, see External issues. And to learn more about controlling the scope of your analysis, see the page on Analysis scope.  

Mandatory parameters

This section lists analysis parameters (sonar properties) that, during a project analysis, cannot be set in the UI and are mandatory. It means that they must be set on the CI/CD host. The following default values are indicated for a parameter when applicable:

• Default from build: It indicates from which build system(s) the scanner can read a default value for the sonar property. The build property used as the default value is not indicated: see the corresponding scanner section for more information.
• Default: This value applies if the property was neither defined on the CI/CD host nor in the UI. 

In addition, if the analysis parameter can be set through an environment variable, the variable name is indicated.

Authentication to the server

• sonar.token
  • Token used by the scanner to authenticate to the SonarQube Server. A token can be specific to a project (allows you to run analyses on the specific project) or global (allows you to run analyses on any project). The corresponding SonarQube user must have the Execute Analysis permission on the project or the Global Execute Analysis permission, respectively.  
  • Notes: 
    • Replaces sonar.login and sonar.password properties that are deprecated.
    • This property can be defined through the SONAR_TOKEN environment variable.
  • Recommendation: It is recommended not to write passwords or authentication tokens in files and not to pass them as parameters in the command line.

Server connection

• sonar.host.url
  • The URL to your SonarQube Server.
  • Default: http://localhost:9000 (the default value is for evaluation purpose only and should not be used in a production context). 
  • Note: This property can be defined through the SONAR_HOST_URL environment variable.

Project identification

• sonar.projectKey
  • The project's unique key. Can include up to 400 characters. All letters, digits, dash, underscore, periods, and colons are accepted. 
  • Default from build: Maven, Gradle.

Optional Parameters

This section lists analysis parameters (sonar properties) that, during a project analysis, cannot be set in the UI (or, like the sonar.projectName, cannot be changed in the UI) and are optional. It means that they can only be set on the CI/CD host. The following default values are indicated for a parameter when applicable:

• Default from build: It indicates from which build system(s) the scanner can read a default value for the sonar property. The build property used as the default value is not indicated: see the corresponding scanner section for more information.
• Default: This value applies if the property was neither defined on the CI/CD host nor in the UI. 

In addition, if the analysis parameter can be set through an environment variable, the variable name is indicated.

Project information

• sonar.projectName
  • Name of the project that will be displayed on the SonarQube UI.
  • Possible values: white space allowed.
  • Default from build: Maven 
  • Notes: 
    • Is set in the UI if the project is manually created in SonarQube (cannot be changed in the UI).
    • If passed in the command line, will only be read by the scanner if the command applies to the main branch. 
• sonar.projectVersion
  • The project version. Is mandatory in case you use the new code definition based on the previous version.
  • Default from build: Maven, Gradle
  • Note: Do not use your build number as the project version because:
    • This would overload the SonarQube database (Houskeeping would not apply to the analysis snapshots because they would be marked by the project version change event).
    • This would prevent a correct application of the new code definition based on the previous project version since the build version usually changes much more often than the project release version.
• sonar.projectDescription
  • The project description.
  • Default from build: Gradle

Analysis scope

Duplication check

Analysis logging

Quality gate

• sonar.qualitygate.wait
  • Forces the analysis step to poll the SonarQube instance and wait for the Quality Gate status. If there are no other options, you can use this to fail a pipeline build when the Quality Gate is failing. 
  • Possible values: true or false
  • Default: false
• sonar.qualitygate.timeout
  • Number of seconds that the scanner should wait for a report to be processed.
  • Default: 300

Import of external issues

This section lists only the properties used to import generic and SARIF issues. For the properties used to import reports generated by third-party tools supported by SonarQube, see Importing third-party issues.

• sonar.externalIssuesReportPaths
  • Comma-delimited list of paths to generic issue reports. 
• sonar.sarifReportPaths
  • Comma-delimited list of paths to SARIF issue reports.

Links displayed in the UI

Multi-branch

The following properties are available from the Developer Edition:

• sonar.branch.name
  • Name of the branch to which the analysis applies.
  • See also Setting up branch analysis.
• sonar.pullrequest.key, sonar.pullrequest.branch, and sonar.pullrequest.base: see Pull request analysis.
• sonar.newCode.referenceBranch
  • Sets the new code definition to Reference Branch  for this analysis, overriding the configuration on the server.  

Other parameters

• sonar.scm.revision
  • Overrides the revision, for instance, the Git sha1, displayed in analysis results.
  • Note: May be provided by the CI environment or guessed from the checked-out sources.
• sonar.buildString
  • The string passed with this property will be stored with the analysis and available in the results of api/project_analyses/search, thus allowing you to later identify a specific analysis and obtain its key for use with api/new_code_periods/set on the SPECIFIC_ANALYSIS type..
• 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.
  • Default: 60
• sonar.sourceEncoding
  • Encoding of the source files. For example, UTF-8, MacRoman, Shift_JIS. The list of available encodings depends on your JVM.
  • Default from build: Maven, Gradle
  • Default: System encoding.
• sonar.working.directory
  • Path to the working directory used by the Sonar scanner during a project analysis to store temporary data. This property is not compatible with the SonarScanner for .NET. 
  • The path can be relative (to the sonar.projectBaseDir property) or absolute. It must be unique for each project.
  • Default from build: Gradle, Maven
  • Default: .scannerwork
  • Warning: The specified directory is deleted before each analysis.

• 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, which may significantly increase analysis duration. This can be useful if you feel that some SCM data is outdated but SonarQube does not get the latest information from the SCM engine and this analysis parameter should not be a permanent part of your analysis configuration.
  • Default: false
• sonar.analysis.<key>=<value>
  • This property stub allows you to insert custom key/value pairs into the analysis context, which will also be passed forward to webhooks.
  • Example: sonar.analysis.buildNumber=12345
  • Note: Depending on the environment, using this property in the command line may not work.

Deprecated parameters

• sonar.login
• sonar.password
• sonar.projectDate