Inspection profiles

Inspection profiles let you configure the inspections, the scope of files that these inspections analyze, and inspection severity settings. Qodana uses inspection profiles to know how and what to inspect in a codebase.

You can employ profiles either using CLI or configuring the qodana.yaml file as shown in the Set up a profile section.

Default profiles

Out of the box, Qodana provides a couple of predefined profiles hosted on GitHub:

qodana.starter is the default profile and a subset of qodana.recommended triggering the 3-phase analysis
qodana.recommended is suitable for CI/CD pipelines and mostly implements the default IDE profiles, see the IntelliJ IDEA documentation for details

How to choose a proper profile

If you want a fresh start, you have two options:

Use Qodana in the default mode to execute the three-phase analysis. You do not need to create the qodana.yaml file in this case, but you can add it later to amend the set of inspections.
Run Qodana using the qodana.recommended profile. In this case, you need to create the qodana.yaml file with a reference to the qodana.recommended profile. This profile contains the inspections for critical or severe issues in the codebase. This profile does not contain any style checks, and non-critical folders, such as tests, are ignored.

Three-phase analysis

Sometimes it may be challenging to set up analysis for a big project even with the qodana.recommended profile due to large number of errors reported. To solve this, Qodana offers a 3-phase analysis, where each phase is focused on a certain type of results.

The first phase is based on the qodana.starter profile that contains vital checks only. Non-critical folders, such as tests, are ignored.
The second phase reports the conditions that could affect truthfulness or completeness of the results. For example, if your project relies on external resources or generated code, and they are not available during the analysis, the final results could be compromised. Qodana notifies you about such suspicious results.
The last phase suggests additional checks that are not so vital for the project but still beneficial. To avoid overwhelming, Qodana analyzes only a fraction of the code, just enough to show you the possible outcome.

Set up a profile

You can set up a profile using either the qodana.yaml file or the shell commands.

Profile name

This is how you can configure the profile name using qodana.yaml:

profile:
    name: <name>

The --profile-name CLI 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:

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

            qodana scan \
               -e QODANA_TOKEN="<cloud-project-token>" \
               -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>
        

            qodana scan \
               -v <path-to-profile-file>/<file-name>:/data/project/.idea/inspectionProfiles/<file-name> \
               -e QODANA_TOKEN="<cloud-project-token>" \
               --profile-name <profile-name-from-file>
        

Profile path

This is how you can configure the profile path using qodana.yaml:

profile:
    path: relative/path/in/your/project.xml

You can use this with custom profiles.

The --profile-path CLI 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:

            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>
        

            qodana scan \
               -v <path-to-profile-file>/<file-name>:/data/project/myprofiles/<file-name> \
               -e QODANA_TOKEN="<cloud-project-token>" \
               --profile-path /data/project/myprofiles/<file-name>
        

Custom profiles

You can configure inspection profiles using two formats:

YAML format is available starting from version 2023.2 of Qodana
XML format can be used as an alternative to YAML

Last modified: 12 April 2024