Shell commands
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.
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 |
|
Linux |
|
Windows |
|
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 |
---|---|
| Root directory of the project |
| Directory to store the analysis results. It should be empty before running Qodana |
| IDE distributive directory |
| IDE configuration directory |
| The default profile file containing the |
| Directory for binding profile files |
| Maven project dependencies |
| Gradle project dependencies |
| NuGet project dependencies |
| Directory containing plugins |
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:
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:
Manage plugins
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:
This script contains several variables explained in the table below.
Variable | Description | Example |
---|---|---|
| The two-character code of the linter that the plugin should be downloaded for. The available values are:
|
|
| Plugin identifier from a plugin page available on JetBrains Marketplace |
|
| Build ID of Qodana available in Qodana logs |
|
You can run Qodana with the plugin file mounted to the plugin 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 ( |
|
Requires the space character ( |
|
Requires no argument |
|
Here is the example command that invokes all these options:
To overview the available options, you can use this command:
Directories
Using these options, you can override the paths described in the Docker image paths section.
Option | Default setting | |
---|---|---|
| Root directory of the inspected project. Files and directories contained in the outside directory are not used while running Qodana |
|
| Directory to save Qodana inspection results to |
|
| Directory for saving the generated HTML report. To open the report, you will need to add the |
|
| Directory to store cache |
|
| Directory inside Files and directories contained in the outside directory like | None |
Override the report directory
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:
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
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:
Using the --cache-dir
option, you can override the cache directory:
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 |
---|---|---|
| Skip running the inspections configured by the | Enabled |
| The profile name taken either from the list of predefined Qodana profiles, or a custom profile name stored in XML-formatted profile files as You can also configure this option using the |
|
| The absolute path to the profile file. You can also configure this option using the | None |
| Run promo inspections as a part of the | Enabled only if Qodana is configured for the |
| Absolute path to the fallback profile file; applied if the profile was not specified using any other method | None |
Profile name
The --profile-name
option lets you run Qodana using either the default profiles or the profile name from the custom profile.
This command lets you override the default profile und run Qodana using the qodana.recommended
profile:
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:
Profile path
The --profile-path
option lets you override the path to the file containing the profile.
This command lets you bind the file to the profile directory, and the --profile-path
option tells Qodana which profile file to read:
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 |
---|---|
| Run Qodana in the baseline mode. Provide the path to an existing SARIF report to be used in the baseline state calculation |
| 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:
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.
Report
This table contains the options related to reports:
Option | Description |
---|---|
| Generate and save HTML-formatted reports |
| Serve HTML-formatted reports. By default, port |
Save the report
The --save-report
option in the Docker command lets you save the generated HTML report to your local filesystem:
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:
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.
Option | Description |
---|---|
| 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:
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.
Properties
Using the --property=
option, you can override various Qodana parameters:
Option | Description |
---|---|
| 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
The default log level for STDOUT is WARN
. You can override it using the idea.log.config.file
property as shown below:
Disable user statistics
To disable reporting of usage statistics, adjust the idea.headless.enable.statistics
value of the --property
option:
Configure plugins
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:
Changes
Option | Description |
---|---|
| Inspect uncommitted changes and report new problems |
Qodana lets you check only locally-modified files using this command:
Run scenario
Option | Description | Default value |
---|---|---|
| Override the default run scenario |
|
Currently, Qodana supports several run scenarios.
Application of the default
run scenario is equivalent to running this command:
To inspect local uncommitted changes, you can use local-changes
value:
To run the PHP version migration scenario, you can run this command:
Qodana Cloud
Option | Description |
---|---|
| 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
fileRun 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:
To learn more about configuring the Heap, see the Heap Tuning Parameters of the Oracle documentation.
Override the idea.properties file
The idea.properties
configures the default locations of the IDE files.
You can override the idea.properties
file using the IDEA_PROPERTIES
variables:
Run as non-root
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:
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.
Order of resolving a profile
Qodana checks the configuration parameters for resolving the inspection profile in this order:
Profile with the name
%name%
from the command-line option--profile-name %name%
Profile by the path
%path%
from the command-line option--profile-path %path%
Profile with the name
%name%
fromqodana.yaml
Profile by the path
%path%
fromqodana.yaml
Profile mounted to
/data/profile.xml
Fall back to using the default
qodana.recommended
profile