Analysis parameters
You can configure project analysis settings in multiple places: in the UI, in scanner configuration files, and as scanner arguments on the command line.
This page explains the analysis settings hierarchy, provides general configuration guidelines, and lists the analysis parameters you cannot set in the UI.
Settings hierarchy
Here is the hierarchy in order of precedence:
Project properties: You can change these properties in the UI and apply them to your project by going to Your Organization > Your Project > Administration > General Settings.
Scanner configuration files: You can configure scanner parameters in a configuration file within your project or a build framework. For CI-based analysis, it depends on the scanner:
pom.xmlfor SonarScanner for Mavenbuild.gradlefor SonarScanner for Gradlepackage.jsonfor SonarScanner for NPMSonarQube.Analysis.xmlfor SonarScanner for .NETPyproject.tomlfor SonarScanner for Pythonsonar-project.propertiesfor SonarScanner CLI
For automatic analysis:
.sonarcloud.propertiesValues set in scanner configuration files will override project properties set in the UI.
Scanner arguments: For CI-based analysis, you can also set parameters on the command line. This can be done with the standalone command-line tool sonar-scanner or with any of the build-tool-specific variants such as SonarScanner for Maven and SonarScanner for Gradle. Scanner arguments override the scanner configuration files.
If you use environment variables, which are available for some properties, they will be overridden by scanner arguments.
General configuration guidelines
Consider the following:
Most of the analysis parameters you can set in the UI can also be set in scanner configuration files or as scanner arguments by using the corresponding sonar properties (a sonar property is a key/value pair in which the key has the
sonar.<property>syntax) .Sonar property keys are case-sensitive.
Some analysis parameters cannot be set in the UI and are listed below in the Mandatory parameters and Optional Parameters articles.
Only parameters you set through the UI are stored in the SonarQube Cloud database. Parameters set in the command line or in the scanner configuration files will only be effective for the current analysis and not for subsequent analyses or analyses in SonarQube for IDE with connected mode. For example, if you override the
sonar.exclusionsparameter via the command line for a specific project, it will not be stored in the database. Subsequent analyses without thesonar.exclusionsparameter in the command line or scanner configuration file, or analyses in SonarQube for IDE, will be executed with the exclusions stored in the database.See the corresponding SonarScanner section in this documentation for general information about the configuration of analysis parameters in scanner configuration files or as scanner arguments:
SonarScanner for NPM: Configuring the scanner
SonarScanner for .NET: Using the scanner
If you use PowerShell, you need to wrap any parameter value that includes a dot (
.) in either single or double quotes to prevent misinterpretation.To adjust the analysis scope of your project, see the Analysis scope pages.
To include test coverage in your project analysis, see the Test coverage pages.
To import issues generated by third-party analyzers, see the External analyzer reports page.
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 Cloud. The corresponding SonarQube Cloud user must have the Execute Analysis permission on the project.
Notes:
From the Team plan, it's recommended to use Scoped Organization Tokens (SOT). See Managing Scoped Organization Tokens.
This property replaces
sonar.loginandsonar.passwordproperties which are deprecated.
Environment variable: SONAR_TOKEN (not supported by SonarScaner for .NET)
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 of the SonarQube Cloud. Must be defined as https://sonarcloud.io.
Environment variable: SONAR_HOST_URL
• For SonarScanners CLI from v6.0, SonarScanner for Maven (from v5.0), Gradle (from v6.0), .NET from v7.0, NPM from v4.0, and Python: https://sonarcloud.io
• Otherwise: http://localhost:9000
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
sonar.organization
The key of the organization to which the project belongs
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 web interface.
Notes:
• Is set in the UI if the project is manually created in SonarQube Cloud (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.
• White space is allowed.
Default from build: Maven
sonar.projectVersion
The project version. It should be set for long-lived branch analysis 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 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.
Default from build:
• Maven
• Gradle
Analysis scope
Check that the specific property key is supported by your scanner. Adding unsupported properties to your .sonarcloud.properties can create problems if the scanner tries to reindex them.
sonar.sources
The initial analysis scope 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 sonar.projectBaseDir property) or absolute. Wildcards (*, ** and ?) are not allowed.
Default from build:
• Maven
• Gradle
• .NET
The value of the sonar.projectBaseDir property.
sonar.tests
The initial analysis scope for test code in the project.
*This property is not supported by the SonarScanner for .NET.
Possible values: See sonar.sources above.
Note: If this property is not defined, no code will be analyzed as test code as there is no default value.
Default from build:
• Maven
• Gradle
• .NET
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 jenkins/jobs/myjob/workspace but the files to be analyzed are in ftpdrop/cobol/project1.
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 sonar.working.directory will be created by default.
Default from build:
• Maven
• Gradle
• .NET
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:
• true: exclusion disable
• false: exclusion enabled
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 sonar.javascript.maxFileSize property (default: 1000 KB) discards JavaScript and TypeScript files from the analysis scope if the file size is greater than specified (This parameter can be set in the UI).
20
Duplication check
sonar.cpd.<language>.minimumTokens
Is used for non-Java projects to define the duplication check rule: a piece of code is considered duplicated if sonar.cpd.<language>.minimumTokens identical tokens are found across at least sonar.cpd.<language>.minimumLines lines of code.
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
sonar.log.level
Controls the quantity/level of logs produced during an analysis.
Possible values: From least to most verbose:
• INFO
• DEBUG
• TRACE: like DEBUG with possible additional information output by plugins or libraries used by the scanner.
INFO
sonar.verbose
Possible values:
• true: adds more details to the analysis logs by activating the DEBUG mode for the scanner.
• false
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.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
sonar.qualitygate.wait
Forces the analysis step to poll the server instance and wait for the Quality Gate status. This setting will fail the pipeline if the quality gate fails.
Possible values: trueor false
false
sonar.qualitygate.timeout
The number of seconds that the scanner should wait for a report to be processed.
300
Test coverage
See the Test coverage parameters page.
Import of external issues
sonar.externalIssuesReportPaths
Comma-delimited list of paths to generic issue reports. See the full list on the External analyzer reports page.
sonar.sarifReportPaths
Comma-delimited list of paths to SARIF reports.
Links displayed in the UI
sonar.links.ci
The URL of the continuous integration system used. The property is effective only for the main branch analysis.
Default from build: Maven
sonar.links.homepage
The URL of the build project home page. The property is effective only for the main branch analysis.
Default from build: Maven
sonar.links.issue
The URL to the issue tracker being used. The property is effective only for the main branch analysis.
Default from build: Maven
sonar.links.scm
The URL of the build project source code repository. The property is effective only for the main branch analysis.
Default from build: Maven
Dependency analysis (SCA)
The following parameters influence the results of the dependency analysis.
sonar.sca.enabled
Boolean
true
Indicates whether to perform Software Composition Analysis (SCA) on this project. Set it to false to disable SCA for this project.
sonar.sca.exclusions
String
A comma-separated list of global patterns of paths to exclude as part of analysis.
For example, to ignore all manifests under the tests/ and fixtures/ directories, set:
sonar.sca.exclusions = "tests/**, fixtures/**"
sonar.sca.allowManifestFailures
Boolean
true
When performing analysis, SonarQube attempts to run your build tools (such as Maven or Gradle) to create a full dependency graph.
By default, SonarQube does not fail the analysis if these tools fail, and returns information on a limited set of dependencies. Set this parameter to false to force a failure in this scenario.
sonar.sca.goNoResolve
Boolean
false
Disables automatic generation of a Go lock file. This results in degraded dependency information.
sonar.sca.mavenNoResolve
Boolean
false
Disables automatic generation of a Maven lock file and dependency graph file.
This results in degraded dependency information.
sonar.sca.mavenForceDepPlugin
Boolean
true
Ensures Maven Dependency Plugin is installed even when it’s not available in the environment.
sonar.sca.mavenIgnoreWrapper
Boolean
false
Disables a search for a Maven wrapper script mvnw. Set this to true if the default Maven wrapper in your PATH is not functioning.
sonar.sca.mavenOptions
String
Sends additional options to any Maven commands used to generate the lock file and dependency graph file.
sonar.sca.gradleNoResolve
Boolean
false
Disables automatic generation of a Gradle dependencies lock file. This results in degraded dependency information.
sonar.sca.gradleConfigurationPattern
String
Java regex of configurations to include. This is passed to gradle via -PconfigurationPattern. When unset, all configurations will be resolved.
sonar.sca.pythonBinary
String
/usr/bin/python
Path to a specific Python binary that should be used if lock files need to be generated.
sonar.sca.pythonNoResolve
Boolean
false
Disables automatic generation of a Python lock file. This results in degraded dependency information.
sonar.sca.pythonResolveLocal
Boolean
false
When generating a python lockfile, dependency resolution is done in a temporary virtual environment. Set this to true to skip creation of the virtual environment and resolve against the local python environment.
sonar.sca.npmNoResolve
Boolean
false
Disables automatic generation of a lock file for an NPM project when a supported lockfile (yarn.lock, package-lock.json, pnpm-lock.yaml, bun.lock) is not present.
sonar.sca.npmEnableScripts
Boolean
false
By default, when generating a lockfile, the --ignore-scripts NPM/Yarn option is passed to ignore any lifecycle scripts. If lifecycle scripts are needed to properly generate dependencies, enable this option.
sonar.sca.nugetNoResolve
Boolean
false
Disables automatic generation of a lock file for a Nuget project.
sonar.scanner.keepReport
Boolean
false
Not specific to SCA. Keeps the scanner work directory after analysis, including the dependency-files.tar.xz that contains dependency files to analyze. Useful if you have access to commercial support, as the Sonar support team may ask for this file to assist with resolving issues.
sonar.sca.resolveAsRoot
Boolean
false
By default, Sonar does not run dependency resolution commands as an administrator, as installing packages could lead to compromise if a malicious package is specified.
While not recommended, you can set this to true if you have vetted your dependencies and need to resolve dependencies while running as an administrator.
JRE auto-provisioning
See also the Scanner's General requirements page for information about JRE auto-provisioning.
JRE auto-provisioning is available only for these SonarScanners:
SonarScanner CLI from v6.0
SonarScanner for Maven from v5.0
SonarScanner for Gradle from v6.0
SonarScanner for .NET from v7.0
SonarScanner for NPM from v4.0
Here are their parameters and environment variables:
sonar.scanner.os
The operating system of the machine hosting the SonarScanner.
Default: the autodetected value
Environment variable: SONAR_SCANNER_OS Not supported by the SonarScanner for .NET.
Possible values: windows, linux, macos, alpine.
sonar.scanner.arch
The CPU architecture type.
Environment variable: SONAR_SCANNER_ARCH Not supported by the SonarScanner for .NET.
Default: the autodetected value
Possible values: x64, aarch64.
sonar.scanner.skipJreProvisioning
Defines whether the JRE auto-detection is disabled (true) or not (false).
Environment variable: SONAR_SCANNER_SKIP_JRE_PROVISIONING Not supported by the SonarScanner for .NET.
Default: false
sonar.scanner.javaExePath
If defined, the SonarScanner will be run with this JRE.
Environment variable: SONAR_SCANNER_JAVA_EXE_PATH Not supported by the SonarScanner for .NET.
Default: The provisioned JRE, or use java from your PATH if sonar.scanner.skipJreProvisioning=true.
Timeout
sonar.scanner.connectTimeout
The time period to establish connections with the server (in seconds).
Default: 5
Supported by: SonarScanner CLI from v6.0, Maven from v5.0, Gradle 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, Maven from v5.0, Gradle 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, Maven from v5.0, Gradle from v6.0, .NET from v7.0, and NPM from v4.0.
sonar.plugins.download.timeout
Maximum time to wait when downloading a plugin from SonarQube (in seconds).
Default: 300
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.
sonar.scanner.proxyHost
The host name of the proxy server (mandatory).
Example: mycompanyproxy.com
Environment variable: SONAR_SCANNER_PROXY_HOST
x
sonar.scanner.proxyPort
The port of the proxy server.
Environment variable: SONAR_SCANNER_PROXY_PORT
Default value:
• If sonar.host.url starts with https: 443
• Otherwise: 80
x
sonar.scanner.proxyUser
In case of an authenticated proxy: the user name.
Environment variable: SONAR_SCANNER_PROXY_USER
x
sonar.scanner.proxyPassword
In case of an authenticated proxy: the user password.
Environment variable: SONAR_SCANNER_PROXY_PASSWORD
x
Branch analysis
The following parameters relate to branch analysis and are, in the main cases, only required when using a non-integrated CI. For detailed information on their use, see the Branch analysis setup page.
sonar.branch.name
The name of the branch to be analyzed.
sonar.branch.target
The name of the target branch of the branch to be analyzed.
Pull request analysis
The following parameters relate to Pull request analysis and are only required for manual projects. For detailed information on their use, see Pull request analysis.
sonar.pullrequest.key
This property is the unique identifier of your Pull Request. Must correspond to the key of the Pull Request in your DevOps platform.
Example: sonar.pullrequest.key=5
sonar.pullrequest.branch
This property is the name of the branch that contains the changes to be merged.
Example: sonar.pullrequest.branch=feature/my-new-feature
sonar.pullrequest.base
The branch into which the pull request will be merged (target branch).
Example: sonar.pullrequest.base=main
main branch
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/project_analyses/set_baseline on the SPECIFIC_ANALYSIS type.
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
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 thesonar.projectBaseDir property) or absolute. It must be unique for each project.
Warning: The specified directory is deleted before each analysis.
Default from build:
• Maven
• Gradle
.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 Cloud 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 your Webhooks.
Example: sonar.analysis.buildNumber=12345
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.
Environment variable: SONAR_USER_HOME
~/.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), SonarScanner for Maven (from v5.0), Gradle (from v6.0) and NPM (from v4.0).
Examples:
SONAR_SCANNER_JAVA_OPTS="-Xmx4g"
Or
SONAR_SCANNER_JAVA_OPTS="-Xmx512m"
Environment variable: SONAR_SCANNER_JAVA_OPTS
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.loginsonar.projectDatehttp.proxyHostorhttps.proxyHosthttp.proxyPorthttp.proxyUserhttp.proxyPasswordsonar.ws.timeout
sonar.scanner.dumpToFile- the name has changed. For more information, see the Debugging the analysis article on the Troubleshooting page.
Last updated
Was this helpful?