Qodana runs are configured via the
qodana.yaml configuration file. Information stored in
qodana.yaml overrides the default inspection profile settings and default configurations of Qodana linters. You can specify such overrides in the HTML report, and the changes are imported to
The JSON schema for
qodana.yaml is published in the SchemaStore project, which allows for completion and basic validation in IDEs.
To run subsequent checks with this customized configuration, save the file to the project's root directory. Alternatively, you can edit the
qodana.yaml configuration file manually. This section will guide you through necessary settings.
Out of the box, Qodana provides several predefined profiles:
empty: an empty profile containing no inspections, which can be used as a basis for manual configuration.
qodana.starter: the default profile that triggers the 3-phase analysis.
qodana.recommended: a profile containing a preselected set of IntelliJ inspections.
qodana.sanity: a profile containing a small preselected set of inspections that perform the project's "sanity" checks. If these checks fail, the project is probably misconfigured, and further examining it will not produce meaningful results. See Qodana linters for details on configuring a project for the desired linter.
You can specify other profiles available in the respective IntelliJ Platform IDE for your source project. If you are using a CI system, make sure the
.xml file with this profile resides in the working directory where the VCS stores your project before building it. The IntelliJ IDEA profiles for embedding into Qodana Docker images are hosted in the qodana-profiles GitHub repository.
How to choose a proper profile
If you already have an inspection profile for your project, you can use it with Qodana as a starting point. You can then adjust it via
qodana.yaml and make it more convenient for the server-side use.
If you want a fresh start, you have two options:
Use Qodana in default mode to execute the three-phase analysis. You don't need to create a
qodana.yamlfile in this case, but you can add it later to amend a set of checks.
Use Qodana with the recommended profile. In this case you need to create a
qodana.yamlfile with a reference to
qodana.recommended. This profile contains the checks for critical or severe issues in the code, which require attention. This profile does not contain any style checks, and non-critical for the project operability folders, such as
tests, are ignored.
Sometimes it may be challenging to set up analysis for a big project even with the
qodana.recommended profile due to large amount 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.starterprofile that contains vital checks only. Non-critical for the project operability 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.
Run custom commands
In particular cases, you may need to have a command or script executed in a Qodana Docker container prior to inspecting your code. It could be done as part of project preparation, software installation, or any other activity that needs to be performed only within the container and that does not affect the Qodana workflow. To solve this task, you can use the
bootstrap option in the
So, if you want to install a specific package in the Qodana container using the
apt tool, you need to add this line to
To run a custom script, save the script file to the project directory and specify execution in
qodana.yaml. For example, this can be:
Set up a profile
Set up a profile by the name
Note that the name of the profile does not necessarily match the name of the containing file stored in
.idea/inspectionProfiles. The actual name is stored as the
<option name="myName" value="%profileName%" /> value in the profile
xml file and is visible in the IDE UI. For details on working with inspection profiles in IDE, see the IDE documentation.
Set up a profile by the path
Exclude paths from the analysis scope
You can specify that the files in a certain directory are not analyzed. This can be done on a per-inspection basis or for all inspections at once. To exclude all paths in a project from the inspection scope, omit the
Exclude all inspections for specified project paths:
Exclude inspections specified by ID for specified project paths:
You can find specific inspection IDs in the Profile settings in the HTML report or in the
.xml file with your inspection profile.
Include an inspection into the analysis scope
You can specify that the files in a certain directory are analyzed by an inspection that is not contained in the selected profile. This can be done on a per-inspection basis. To include all paths in a project into the inspection scope, omit the
In this example, the
empty profile, which contains no inspections, is specified, and the
SomeInspectionId inspection is explicitly included into the analysis scope for the
tools directory. As a result, only the check performed by the
SomeInspectionId inspection the
tools directory contents will be included in the Qodana run.
Set a fail threshold
Add a fail threshold to use as a quality gate:
When this number of problems is reached, the container executes
exit 255. This can be used to make a CI step fail. The default value is
Override the default run scenario
You can override the standard Qodana behavior, which can be helpful in the case of the PHP version migration. To inspect your code from this perspective, you can run the
By default, Qodana employs the
default scenario, which means the normal Qodana run equivalent to this setting:
Example of different configuration options
In the example above,
SomeInspectionIdinspection is explicitly enabled for all paths, although it is disabled in the profile
Annotatorinspection is disabled for all paths
AnotherInspectionIdinspection is disabled for
no inspections are conducted over these paths:
Disable sanity checks
By default, sanity checks are enabled in Qodana. You can disable them using this snippet:
License audit configuration
You can enable the License audit feature using the
Ignore a dependency
Ignore a dependency to hide the related problems from the report:
name is the dependency name to ignore.
In the example above, in the analyzed project, the dependency
enry is completely excluded from the analysis, any possible license-related problems are dismissed, the dependency won't be included in the report at all. This is useful to quickly hide internal dependencies that do not need to be mentioned in the report.
Allow or prohibit a license
Override the predefined license compatibility matrix:
keys is the project license(s); the dependency licenses identifiers are specified in
Override a dependency license
Override a dependency license identifier:
name is the dependency name,
version is the dependency version, and
licenses is the list of redefined dependency licenses.
In the example above, you 'tell' Qodana to detect CDDL-1.1, GPL-2.0-with-classpath-exception and no other licenses for jaxb-runtime (only 2.3.1). This is useful when a dependency is dual-licensed and you want to omit some license or when it's not possible to detect the license from the dependency sources correctly.
Currently, license audit with Qodana is possible only for JPS, Maven, Gradle, npm, yarn and composer projects. If you want to include the dependency that should be mentioned in the report but is impossible to detect from the project sources, you can use
customDependencies to specify it:
Clone Finder license overrides
You need license overrides when you want to stop seeing warnings about certain mismatched licenses in Clone Finder's reports. For example, Clone Finder's default license compatibility matrix specifies that a queried project with the GPL-3.0-only license may not use code from projects with the ISC license. That's why Qodana Clone Finder will show a warning for duplicate code fragments with such mismatched licenses. However, if your legal advisor says it is OK, you can specify to ignore warnings for this specific license in reference projects. You can do so in the HTML report via the Problem explorer or directly in
qodana.yaml as shown in the example below.
In the example above, using code from ISC reference projects (
target) is allowed in the GPL-3.0-only queried project (
source), although this combination is listed as incompatible, for example, in choosealicense.com/appendix/.