Qodana
 
2023.2
You are viewing the documentation for an earlier version of Qodana.
  1. Configuration
  2. Shell commands

Shell commands

Edit page Last modified: 28 November 2023

This section explains how you can configure the Docker images of Qodana and the Qodana CLI tool. You can use both tools locally and in CI/CD pipelines.

In several cases, you can configure them using the qodana.yaml file, which is also mentioned in this section.

Starting from version 2022.3 of Qodana, the Ultimate and Ultimate Plus linters require the QODANA_TOKEN variable to refer to the project token. If you run the Community linters of Qodana, using QODANA_TOKEN is necessary only if you wish to view Qodana reports in Qodana Cloud.

Qodana CLI

Qodana CLI stores files in the <userCacheDir> directory, which is mentioned several times throughout this section. Here is the list of <userCacheDir> directory locations depending on the operating system:

Operating System

Path

macOS

~/Library/Caches/

Linux

~/.cache/

Windows

%LOCALAPPDATA%\

If you run the qodana init command in the project directory, Qodana CLI will let you choose the linter that will be run during inspection, and saves the choice in qodana.yaml. Once done, you do not need to specify the linter in the commands, which is shown throughout this section.

Paths

This table lists the paths contained in Docker images and Qodana CLI:

Path

Description

/data/project

Root directory of the project

/data/results

Directory to store the analysis results. It should be empty before running Qodana

/opt/idea

IDE distributive directory

/root/.config/idea

IDE configuration directory

/data/profile.xml

The default profile file containing the qodana.starter profile configuration. This file is used if a profile was not previously configured either via the CLI or the qodana.yaml file. See Order of resolving a profile for details

/data/project/.idea/inspectionProfiles/

Directory for binding profile files

/data/cache/.m2

Maven project dependencies

/data/cache/gradle

Gradle project dependencies

/data/cache/nuget

NuGet project dependencies

/opt/idea/plugins

Directory containing plugins

/data/coverage

Directory for mapping code coverage files

Below you can find several examples of how these paths can be applied.

Override the default inspection profile

By default, Qodana employs the qodana.starter profile, but you can bind and use your own profile instead:

$
docker run \
   -v $(pwd):/data/project/ \
   -v $(pwd)/<profile-file>:/data/profile.xml \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter>

To learn more about profiles, see the Order of resolving a profile and Set up a profile sections in this documentation.

Override Gradle settings

In case of JVM linters, you can override the default Gradle settings:

$
docker run \
   -v $(pwd):/data/project/ \
   -v $(pwd)/gradle.properties:/data/cache/gradle/gradle.properties \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter>

Manage plugins

note

This feature is not available in the Qodana for .NET linter.

note

Paid plugins are not yet supported. Each vendor must clarify licensing terms for CI usage and collaborate with us to make it work.

You can automatically download the required plugins from JetBrains Marketplace and use them in your CI/CD pipelines. For example, this Shell script will download the Twig plugin:

IDE_CODE=PS
PLUGIN_ID="com.jetbrains.twig"
BUILD_ID="231.7515"
curl -L -o "$PLUGIN_ID".zip "https://plugins.jetbrains.com/pluginManager?action=download&id=$PLUGIN_ID&build=$IDE_CODE-$BUILD_ID" && unzip "$PLUGIN_ID".zip

This script contains several variables explained in the table below.

Variable

Description

Example

IDE_CODE

The two-character code of the linter that the plugin should be downloaded for. The available values are:

PS

PLUGIN_ID

Plugin identifier from a plugin page available on JetBrains Marketplace

com.jetbrains.twig from the Twig plugin page

BUILD_ID

Build ID of Qodana available in Qodana logs

Starting up Qodana for PHP 2023.2 EAP (build QDPHP-231.7515)

You can run Qodana with the plugin file mounted to the plugin directory:

$
docker run \
   -v $(pwd):/data/project/ \
   -v <path-to-plugin>/<plugin-name>:/opt/idea/plugins/<plugin-name> \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter>

Overview Qodana logs

Depending on the tool, you can view log files generated by Qodana:

You can mount the $(pwd)/.qodana/results/ directory to the /data/results directory of the Docker image:

$
docker run \
   -v $(pwd):/data/project/ \
   -v $(pwd)/.qodana/results/:/data/results \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter>

Once the Qodana run is complete, you can view log files in the $(pwd)/.qodana/results/ directory.

Options

Docker images can be configured using several CLI options. All these options can be divided into three groups.

Option type

Example

Requires the equal sign (=) between the option name and its argument

--property=idea.log.config.file=info.xml

Requires the space character ( ) between the option name and its argument

--baseline /path/to/sarif/file

Requires no argument

--show-report

Here is the example command that invokes all these options:

$
docker run \
   -p 8080:8080 \
   -v $(pwd):/data/project/ \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --property=idea.log.config.file=info.xml \
   --baseline <baseline-path> \
   --show-report

To see the available options, you can use this command:

$
docker run jetbrains/qodana-<linter> -h

Directories

Using these options, you can override the paths described in the Docker image paths section.

Option

Default setting

-i, --project-dir

Root directory of the inspected project.

Files and directories contained in the outside directory are not used while running Qodana

/data/project

-o, --results-dir

Directory to save Qodana inspection results to

/data/results

-r, --report-dir

Directory for saving the generated HTML report. To open the report, you will need to add the --save-report option.

note

This option is not available in Qodana CLI.

/data/results/report

--cache-dir

Directory to store cache

/data/cache

-d, --source-directory

Directory inside --project-dir. If missing, the whole project is inspected

Files and directories contained in the outside directory like .git and build.gradle are used by Qodana while inspecting code

None

Override the report directory

tip

During inspection, Qodana CLI automatically saves inspection reports in the ./<userCacheDir>/JetBrains/Qodana/<linter>/<project-id>/results/report directory.

Here, the linter and project-id directories have the hash format.

This Docker command overrides the default report directory using the --report-dir option, and saves the generated report to the local filesystem using the --save-report option:

$
docker run \
   -v $(pwd):/data/project/ \
   -v <html-report-directory>:/data/results/newreportdir/ \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --report-dir /data/results/newreportdir/ \
   --save-report

The generated report is saved to the local filesystem as per the -v <html-report-directory>:/data/results/newreportdir/ line in this command.

Cache dependencies

tip

Qodana CLI automatically manages cache and requires no action.

After the first run, Qodana CLI stores cache in the ./<userCacheDir>/JetBrains/<linter>/cache directory.

You can improve Qodana performance by persisting cache between runs. For example, package and dependency management tools such as Maven, Gradle, npm, Yarn, and NuGet keep a local cache of downloaded dependencies.

By default, Qodana save caches to the /data/cache directory inside a container. You can override this location using the --cache-dir option. This data is per-repository, so you can pass cache from branch-a to build checking branch-b. In this case, only new dependencies would be downloaded if they were added.

This command maps the local directory with the /data/cache directory of the Docker image, which saves cache to your local filesystem:

$
docker run \
   -v $(pwd):/data/project/ \
   -v <local-cache-directory>:/data/cache/ \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter>

Using the --cache-dir option, you can override the cache directory:

$
docker run \
   -v $(pwd):/data/project/ \
   -v <local-cache-directory>:/data/newcachedir/ \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --cache-dir /data/newcachedir

In a GitHub workflow, you can use dependency caching. GitLab CI/CD also has the cache that can be stored only inside the project directory. In this case, you can exclude the cache directory from inspection via qodana.yaml.

Profile

By default, Qodana inspects your code using the qodana.starter profile.

You can configure and override Qodana profiles either in the qodana.yaml file, or using the CLI options from this table

Option

Description

Default setting

--disable-sanity

Skip running the inspections configured by the qodana.sanity profile

Enabled

-n, --profile-name

The profile name taken either from the list of predefined Qodana profiles, or a custom profile name stored in XML-formatted profile files as <option name="myName" value="%profileName%"/>.

You can also configure this option using the qodana.yaml file

qodana.starter

-p, --profile-path

The absolute path to the profile file.

You can also configure this option using the qodana.yaml file

None

--run-promo

Run promo inspections as a part of the qodana.starter profile

note

This option is not available in the Qodana for .NET linter.

Enabled only if Qodana is configured for the qodana.starter profile, and the --run-promo true option is invoked

Profile name

The --profile-name option lets you run Qodana using either the default profiles or the profile name from the custom profile.

tip

You can also configure this option using the qodana.yaml file.

This command lets you override the default profile und run Qodana using the qodana.recommended profile:

$
docker run \
   -v $(pwd):/data/project/ \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --profile-name qodana.recommended

If you need to run Qodana with a custom profile, you can use its actual profile name.

This command lets you bind a custom profile:

$
docker run \
   -v $(pwd):/data/project/ \
   -v <path-to-profile-file>/<file-name>:/data/project/.idea/inspectionProfiles/<file-name> \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --profile-name <profile-name-from-file>

Profile path

The --profile-path option lets you override the path to the file containing the profile.

tip

You can also configure this option using the qodana.yaml file.

This command lets you bind the file to the profile directory, and the --profile-path option tells Qodana which profile file to read:

$
docker run \
   -v $(pwd):/data/project/ \
   -v <path-to-profile-file>/<file-name>:/data/project/myprofiles/<file-name> \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --profile-path /data/project/myprofiles/<file-name>

Baseline

In the baseline run mode, each new Qodana run is compared to some initial run. This can help in situations when you have no possibility to fix old problems and rather want to prevent the appearance of new ones.

To use the baseline feature, first run Qodana, and in the report UI select the problems that will be considered as baseline. Finally, save the SARIF-formatted file containing the baseline problems.

This is the list of baseline-related options:

Option

Description

-b, --baseline

Run Qodana in the baseline mode. Provide the path to an existing SARIF report to be used in the baseline state calculation

--baseline-include-absent

Include in the output report the results from the baseline run that are absent in the current run

This is the command that invoke all baseline options:

$
docker run \
   -v $(pwd):/data/project/ \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --baseline <path-to-the-SARIF-file> \
   --baseline-include-absent

Here, the <path-to-the-SARIF-file> is the path to a qodana.sarif.json file relative to the project root and taken from a previous Qodana run. If --baseline-include-absent is invoked, the inspection results will include absent problems or the problems detected only in the baseline run but not in the current run.

Based on this run, the SARIF output report will contain the per-problem information on the baseline state.

Code coverage

You can run the code coverage by mapping the directory containing code coverage files to the /data/coverage directory of a Qodana linter image:

$
docker run \
   -v /my/dir/with/coverage:/data/coverage \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter>

Report

This table contains the options related to reports:

Option

Description

-s, --save-report

Generate and save HTML-formatted reports

-w, --show-report

Serve HTML-formatted reports. By default, port 8080 is used

Save the report

tip

During inspection, Qodana CLI automatically saves inspection reports in the ./<userCacheDir>/JetBrains/Qodana/<linter>/<project-id>/results/report directory.

Here, the linter and project-id directories have the hash format.

The --save-report option in the Docker command lets you save the generated HTML report to your local filesystem:

$
docker run \
   -v $(pwd):/data/project/ \
   -v <directory-to-save-report-to>:/data/results/report \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --save-report

Show the report

This command runs the web server on port 4040 of a host machine, so your report will be available on http://localhost:4040:

$
docker run \
   -p 4040:8080 \
   -v $(pwd):/data/project/ \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --show-report

To stop the web server, press Ctrl-C in the Docker console.

Quality gate

Qodana lets you configure a quality gate or the number of problems that will act as a threshold. Once the threshold is reached, the inspection run is terminated.

tip

You can specify the threshold by adding the failThreshold: <number> node to qodana.yaml. However, the Docker command option overrides the settings in the qodana.yaml file.

Option

Description

--fail-threshold

Set the number of problems that will serve as a quality gate

Here is the command that tells Qodana to fail the build in case the number of problems exceeds 10:

$
docker run \
   -v $(pwd):/data/project/ \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --fail-threshold 10

If you run Qodana with the baseline mode enabled, a threshold is calculated as the sum of new and absent problems. The unchanged results are ignored.

Quick-fix

To apply quick-fix strategies to your codebase, you can invoke the --fixes-strategy option.

$
docker run \
   -v <source-directory>/:/data/project/ \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --fixes-strategy <cleanup/apply>

Properties

Using the --property= option, you can override various Qodana parameters:

Option

Description

--property=

Set a JVM property using this notation:

--property=property.name=value1,...,valueN

This option can be repeated multiple times for setting multiple JVM properties.

Log INFO messages to STDOUT

note

This feature is not available in the Qodana for .NET linter.

The default log level for STDOUT is WARN. You can override it using the idea.log.config.file property as shown below:

$
docker run \
   -v $(pwd):/data/project/ \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --property=idea.log.config.file=info.xml

Disable user statistics

To disable reporting of usage statistics, adjust the idea.headless.enable.statistics value of the --property option:

$
docker run \
   -v $(pwd):/data/project/ \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --property=idea.headless.enable.statistics=false

Configure plugins

note

Paid plugins are not yet supported. Each vendor must clarify licensing terms for CI usage and collaborate with us to make it work.

Using the idea.required.plugins.id and idea.suppressed.plugins.id properties, you can specify the plugins required for a specific run, and the list of plugins that will be suppressed:

$
docker run \
   -v $(pwd):/data/project/ \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --property=idea.required.plugins.id=JavaScript,org.intellij.grails \
   --property=idea.suppressed.plugins.id=com.intellij.spring.security

Changes

warning

This option is deprecated and will be removed soon. For all linters, use --script local-changes instead.

Option

Description

-c, --changes

Inspect uncommitted changes and report new problems

Qodana lets you check only locally-modified files using this command:

$
docker run \
   -v $(pwd):/data/project/ \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --changes

Run scenario

Option

Description

Default value

--script

Override the default run scenario

default

tip

You can also configure this option using the qodana.yaml file.

Currently, Qodana supports several run scenarios.

Application of the default run scenario is equivalent to running this command:

$
docker run \
   -v $(pwd):/data/project/ \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --script default

To inspect local uncommitted changes, you can use local-changes value:

$
docker run \
   -v $(pwd):/data/project/ \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --script local-changes

To run the PHP version migration scenario, you can run this command:

$
docker run \
   -v $(pwd):/data/project/ \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --script php-migration:<old-php-version>−to−<upgraded-php-version>

Qodana Cloud

Option

Description

-a, --analysis-id=

Unique report identifier (GUID) to be used by Qodana Cloud

To forward reports to Qodana Cloud, you can set the list of Docker environments as explained in the Forward reports section.

Docker variables

Using the -e and -u Docker parameters, you can:

  • Change the Heap size

  • Override the idea.properties file

  • Run Qodana as non-root

  • Forward Qodana reports to Qodana Cloud

Change the Heap size

By default, the Heap size is set to 80% of the host RAM. You can configure this setting using the _JAVA_OPTIONS variable:

$
docker run \
   -v $(pwd):/data/project/ \
   -e _JAVA_OPTIONS=-Xmx6g \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter>

To learn more about configuring the Heap, see the Heap Tuning Parameters of the Oracle documentation.

Override the idea.properties file

note

This feature is not available in the Qodana for .NET linter.

The idea.properties configures the default locations of the IDE files.

You can override the idea.properties file using the IDEA_PROPERTIES variables:

$
docker run \
   -v $(pwd):/data/project/ \
   -e IDEA_PROPERTIES=/data/project/idea.properties \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter>

Run as non-root

tip

TeamCity and Qodana CLI already run Qodana under a current non-root user.

By default, a container runs under the root user so that Qodana can read project information and write inspection results. Therefore, all files in the results/ directory are owned by the root user after the run.

To overcome this, you can run the container as a regular user:

$
docker run \
   -u $(id -u):$(id -g) \
   -v $(pwd):/data/project/ \
   -v <results-directory>:/data/results/ \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter>

In this case, the results/ directory on host should already be created and owned by you. Otherwise, Docker will create it as the root user, and Qodana will not be able to write to it.

Forward reports to Qodana Cloud

You can forward Qodana reports to Qodana Cloud by specifying the QODANA_TOKEN variable that will contain the Qodana Cloud project token.

Using Docker also requires a bunch of variables described in the Forward reports section.

$
docker run \
   -v $(pwd):/data/project/ \
   -e QODANA_TOKEN="<qodana-cloud-token>" \
   -e QODANA_REMOTE_URL="<project-remote-url>" \
   -e QODANA_BRANCH="<project-branch-name>" \
   -e QODANA_REVISION="<commit-hash>" \
   -e QODANA_JOB_URL="<job-url>" \
   jetbrains/qodana-<linter>

Order of resolving a profile

Qodana checks the configuration parameters for resolving the inspection profile in this order:

  1. Profile with the name %name% from the command-line option --profile-name %name%

  2. Profile by the path %path% from the command-line option --profile-path %path%

  3. Profile with the name %name% from qodana.yaml

  4. Profile by the path %path% from qodana.yaml

  5. Profile mounted to /data/profile.xml

  6. Fall back to using the default qodana.recommended profile