Analysis parameters
On this page
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:
- Global properties: Apply to all projects. Defined in the UI in Administration > Configuration > General Settings
- Project properties: Apply to one project only. At project level, defined in the UI in Project Settings > General Settings
- Project analysis parameters: Defined in a project analysis configuration file or scanner configuration file
- Analysis / Command line parameters: Defined when launching an analysis with
-D
on the command line
There is an exception to this settings hierarchy. You can use two parameters in the UI, Global Source File Exclusions and Global Test File Exclusions, to define the global analysis scope at the global level and you cannot override them at the project level: see Analysis scope for more details.
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.
Analysis parameters are case-sensitive.
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
Property key | Description |
---|---|
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. Note: Replaces 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
Property key | Description | Default |
---|---|---|
sonar.host.url | The URL to your SonarQube Server. You must define this URL because the SonarScanners also work with SonarCloud which uses a different URL. Environment variable: |
|
Project identification
Property key | Description |
---|---|
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:
|
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
Property key | Description |
---|---|
sonar.projectName | The name of the project that will be displayed on the SonarQube UI. Notes:
Default from build: Maven |
sonar.projectVersion | The project version. Is mandatory in case you use the new code definition based on the previous version. Note: Do not use your build number as the project version because:
Default from build:
|
sonar.projectDescription | The project description. Note: This property is not supported by the SonarScanner for .NET. Default from build: Gradle |
Analysis scope
Property key | Description | Default |
---|---|---|
sonar.sources | The analysis baseline for main source code (non-test code) in the project. *This property is not supported by the SonarScanner for .NET. Possible values: Comma-separated paths to directories are included. An individual file in the list means that the file is included. A directory in the list means that all analyzable files and directories recursively below it are included. The path can be relative (to the Default from build:
| The value of the sonar.projectBaseDir property. |
sonar.tests | The analysis baseline for test code in the project. *This property is not supported by the SonarScanner for .NET. Possible values: See Note: If this property is not defined, no code will be analyzed as test code as there is no default value. Default from build:
| |
sonar.projectBaseDir | The project’s base directory. Use this property when you need the analysis to take place in a directory other than the one from which it was started. For example, the analysis starts from Possible values: The path may be relative (to the directory from which the analysis was started) or absolute. Specify not the source directory, but some ancestor 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 that specified value. Note: The analysis process will need Write permissions in this directory; it is where the Default from build:
| The directory from which the analysis was started. |
sonar.scm.exclusions.disabled | For supported SCMs, defines whether files ignored by the SCM, e.g., files listed in .gitignore, will be excluded from the analysis or not. Possible values:
| false |
sonar.filesize.limit | Sets the limit in MB for files to be discarded from the analysis scope if the size is greater than specified. Note: The | 20 |
Duplication check
Property key | Description | Default |
---|---|---|
sonar.cpd.<language>.minimumtokens | Is used for non-Java projects to define the duplication check rule: a piece of code is considered duplicated if Note: For Java projects, a piece of code is considered 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 | Is used for non-Java projects to define the duplication check rule: see above. | 10 |
Analysis logging
Property key | Description | Default |
---|---|---|
sonar.log.level | Controls the quantity/level of logs produced during an analysis. Possible values: From least to most verbose:
| INFO |
sonar.verbose | Possible values:
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.scanner.dumpToFile | Outputs to the specified file the full list of properties passed to the scanner API as a means to debug analysis. The equivalent output is available in Your Project > Project Settings > Background Tasks > 3-dots menu > Show SonarScanner Context. Possible values: path to the output file name Note: If the analysis report fails, the list is not generated and there won't be anything available on the server. | |
sonar.scanner.metadataFilePath | Sets the location where the scanner writes the report-task.txt file containing among other things the ceTaskId . | The value of sonar.working.directory . |
Quality gate
Property key | Description | Default |
---|---|---|
sonar.qualitygate.wait | Forces the analysis step to poll the server 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: | false |
sonar.qualitygate.timeout | The number of seconds that the scanner should wait for a report to be processed. | 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.
Property key | Description |
---|---|
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
Property key | Description |
---|---|
sonar.links.ci | The URL of the continuous integration system used. Default from build: Maven |
sonar.links.homepage | The URL of the build project home page. Default from build: Maven |
sonar.links.issue | The URL to the issue tracker being used. Default from build: Maven |
sonar.links.scm | The URL of the build project source code repository. Default from build: Maven |
Multi-branch
The properties below are available from the Developer Edition.
Property key | Description |
---|---|
sonar.branch.name | The name of the branch to which the analysis applies. See also Setting up the branch analysis. |
sonar.pullrequest.key , sonar.pullrequest.branch , and sonar.pullrequest.base | See Setting up the pull request analysis. |
sonar.newCode.referenceBranch | Sets the new code definition to Reference Branch for this analysis, overriding the configuration on the server. |
JRE auto-provisioning
JRE auto-provisioning is available only for these SonarScanners:
- SonarScanner CLI from v6.0
- SonarScanner for .NET from v7.0
- SonarScanner for NPM from v4.0
Here are their parameters and environment variables:
Property key | Description |
---|---|
sonar.scanner.os | The operating system of the machine hosting the SonarScanner. Default: the autodetected value Environment variable: Possible values: |
sonar.scanner.arch | The CPU architecture type. Environment variable: Default: the autodetected value Possible values: |
sonar.scanner.skipJreProvisioning | Defines whether the JRE auto-detection is disabled ( Environment variable: Default: |
sonar.scanner.javaExePath | If defined, the SonarScanner will be run with this JRE. Environment variable: Default: The provisioned JRE, or use java from your PATH if |
Timeout
Property key | Description |
---|---|
sonar.scanner.connectTimeout | The time period to establish connections with the server (in seconds). Default: 5 Supported by: SonarScanner CLI from v6.0, .NET from v7.0, and NPM from v4.0. |
sonar.scanner.socketTimeout | The Maximum time of inactivity between two data packets when exchanging data with the server (in seconds). Default: 60 Supported by: SonarScanner CLI from v6.0, .NET from v7.0, and NPM from v4.0. |
sonar.scanner.responseTimeout | The 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 Supported by: SonarScanner CLI from v6.0, .NET from v7.0, and NPM from v4.0. |
sonar.ws.timeout | Same as the Note: This property is not supported by the SonarScanner for .NET Default: 60 |
Proxy
If the CI/CD host is behind a proxy, you’ll have to setup the connection to the proxy server by using the parameters below.
Note: The SonarScanner for .NET does not support any of the property keys listed here.
Property key | Description | Supported only by SonarScanner CLI (from v6.0) and NPM (from v4.0) |
---|---|---|
sonar.scanner.proxyHost | The host name of the proxy server (mandatory). Example: Environment variable: | x |
sonar.scanner.proxyPort | The port of the proxy server. Environment variable: Default value:
| x |
sonar.scanner.proxyUser | In case of an authenticated proxy: the user name. Environment variable: | x |
sonar.scanner.proxyPassword | In case of an authenticated proxy: the user password. Environment variable: | x |
http.proxyHost or https.proxyHost | Same as sonar.scanner.proxy | |
http.proxyPort | Same as sonar.scanner.proxyport | |
http.proxyUser | Same as sonar.scanner.proxyUser | |
http.proxyPassword | Same as sonar.scanner.proxyPassword |
TLS
For more information, see Managing the TLS certificates on the client side.
All the parameters listed below are supported only by the SonarScanner CLI (from version 6.0) and the SonarScanner for NPM (from version 4.0). The SonarScanner for .NET does not support any of the property keys listed here.
Property key | Description | Default |
---|---|---|
sonar.scanner.truststorePath | The path to the keystore file. | <sonar.userHome>/ssl/truststore.p12 |
sonar.scanner.truststorePassword | The password of the truststore. | sonar |
sonar.scanner.keystorePath | The path to the keystore file | <sonar.userHome>/ssl/keystore.p12 |
sonar.scanner.keystorePassword | The password of the keystore file | sonar |
Other parameters
Property key | Description | Default |
---|---|---|
sonar.scm.revision | Overrides the revision, for instance, the Git 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.sourceEncoding | Encoding of the source files. For example, Default from build:
| The 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 Warning: The specified directory is deleted before each analysis. Default from build:
| .scannerwork |
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. | 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: Note: Depending on the environment, using this property in the command line may not work. | |
sonar.userHome | The base directory for various locations, such as the user cache. It must be located inside the user home directory. Environment variable: | ~/.sonar |
sonar.scanner.javaOpts | Since SonarScanner CLI 6.0.0, the scanner engine will be started as a separate Java process. This property is used to pass arguments to the JVM running the forked scanner engine process. Can be used only with the SonarScanner CLI (from v6.0) and the SonarScanner for NPM (from v4.0). Examples:
Or
Environment variable: |
Deprecated parameters
These parameters are listed for completeness, but are deprecated and should not be used in new analyses. They will be removed in the future. A user warning appears on the project interface if you activate this parameter.
sonar.login
sonar.password
sonar.projectDate
Was this page helpful?