YAML file

By default, Qodana reads configurations from the qodana.yaml file contained in the root directory of your project. You can override this filename using the --config option, see the Custom configuration file for details. For convenience, this will be referred in this section using the default qodana.yaml name.

Configuration applied in qodana.yaml override the default inspection profile settings and default configurations of Qodana linters, you can configure it using the HTML report section, and all changes will be applied automatically.

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 the necessary settings.

Run custom commands

Using the bootstrap key of qodana.yaml, Qodana can perform actions before running the analysis.

To install a specific package in the Qodana container using the apt tool, add this line to qodana.yaml:

bootstrap: apt install <package_name>

To run a script, save the prepare-qodana.sh script file to the project directory and specify execution in qodana.yaml:

bootstrap: sh ./prepare-qodana.sh

To learn more about use-cases, see the Prepare your project section.

Set up a profile

Profile invocation is explained in the Inspection profiles section. Information about custom profiles is also provided here.

Exclude paths from the analysis scope

You can exclude files and paths from analyses on a per-inspection basis and for all inspections at once. Information about inspection IDs is available on the Inspectopedia website.

To exclude all paths in a project from the analysis scope, omit the paths node.

Examples

Exclude all inspections for specified project paths:

exclude:
  - name: All
    paths:
      - asm-test/src/main/java/org
      - asm/Visitor.java
      - benchmarks

Exclude inspections specified by ID for specified project paths:

exclude:
  - name: Annotator
  - name: AnotherInspectionId
    paths:
      - relative/path
      - another/relative/path
  - name: All
    paths:
      - asm-test/src/main/java/org
      - asm
      - benchmarks
      - tools

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 tell Qodana to analyze files of a certain directory 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 paths node. Information about inspection IDs is available on the Inspectopedia website.

Example

In this example, the empty profile, which contains no inspections, is specified, and the SomeInspectionId inspection is explicitly included in 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.

  profile:
  name: empty
include:
  - name: SomeInspectionId
    paths:
    - tools

Set a quality gate

You have several options to configure quality gates.

First of all, you can add a fail threshold to control the total number of problems in a project, which is supported by all linters:

failThreshold: <number>

All linters except Qodana Community for .NET let you use the following configuration:

failureConditions:
  severityThresholds:
    any: <number> # Total problems
    critical: <number> # Critical and other severities
    high: <number>
    moderate: <number>
    low: <number>
    info: <number>
  testCoverageThresholds:
    fresh: <number> # Fresh code coverage
    total: <number> # Total code coverage

In this configuration, exceeding just one setting limitation will make the build fail.

The severityThresholds:any option lets you configure the total number of problems. Options like severityThresholds:critical let you configure quality gates for each problem severity. The testCoverageThresholds:fresh and testCoverageThresholds:total options let you configure the total and fresh code coverage supported by several linters.

Override the default run scenario

script:
  name: <script-name>
  parameters:
      <parameter>: <value>

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 php-migration scenario.

By default, Qodana employs the default scenario, which means the normal Qodana run equivalent to this setting:

script:
  name: default

Example of different configuration options

version: 1.0
failThreshold: 0
profile:
  name: qodana.recommended
include:
  - name: SomeInspectionId
exclude:
  - name: Annotator
  - name: AnotherInspectionId
    paths:
      - relative/path
      - another/relative/path
  - name: All
    paths:
      - asm-test/src/main/java/org
      - benchmarks
      - tools

In the example above,

SomeInspectionId inspection is explicitly enabled for all paths, although it is disabled in the profile
Annotator inspection is disabled for all paths
AnotherInspectionId inspection is disabled for relative/path and another/relative/path
no inspections are conducted over these paths: asm-test/src/main/java/org, benchmarks, tools

Specify a linter

Using the linter option, you can specify a linter that you are going to employ. For example:

linter: jetbrains/qodana-jvm-android:2024.3

Configure the JDK version

You can configure the JDK version for these linters:

Use the projectJDK option to specify the JDK version, for example:

projectJDK: 11

or:

projectJDK: 1.8

You can also specify JDK using the name:

projectJDK: corretto-19

To learn more about configuring JDK, see the Configure the JDK section.

Configure the PHP version

You can configure the PHP version before running the Qodana for PHP linter:

php:
  version: "X.x"

Disable sanity checks

By default, sanity checks are enabled in Qodana. You can disable them using this snippet:

disableSanityInspections: true

Configure license audit

Starting from version 2024.1 of Qodana, the license audit feature is enabled by default. You can disable it by excluding the CheckDependencyLicenses inspection:

exclude:
  - name: CheckDependencyLicenses

Ignore a dependency

Ignore a dependency to hide the related problems from the report:

dependencyIgnores:
  - name: "enry"

where name is the dependency name to ignore.

In the example above, the enry dependency is completely excluded from the analysis. Because 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:

licenseRules:
  - keys:
      - "PROPRIETARY-LICENSE"
      - "MIT"
    prohibited:
      - "BSD-3-CLAUSE-NO-CHANGE"
    allowed:
      - "ISC"

  - keys: [ "Apache-2.0" ]
    prohibited:
      - "MIT"

where keys is the project license(s); the dependency licenses identifiers are specified in allowed or prohibited.

Override a dependency license

Override a dependency license identifier:

dependencyOverrides:
  - name: "jaxb-runtime"
    version: "2.3.1"
    url: "https://github.com/javaee/jaxb-v2"
    licenses:
      - key: "CDDL-1.1"
        url: "https://github.com/javaee/jaxb-v2/blob/master/LICENSE"
      - key: "GPL-2.0-with-classpath-exception"
        url: "https://github.com/javaee/jaxb-v2/blob/master/LICENSE"

where 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.

Custom dependencies

Currently, the license audit with Qodana is possible only for JPS, Maven, Gradle, npm, yarn and composer projects. To include the dependency that should be mentioned in the report but is impossible to detect from the project sources, use customDependencies to specify it:

customDependencies:
  - name: ".babelrc JSON Schema (.babelrc-schema.json)"
    version: "JSON schema for Babel 6+ configuration files"
    licenses:
      - key: "Apache-2.0"
        url: "https://github.com/SchemaStore/schemastore/blob/master/LICENSE"

Configure quick-fixes

Using the fixesStrategy option, you can choose among the available quick-fix strategies:

fixesStrategy: cleanup/apply

Configure the taint analysis

In the qodana.yaml file, include the PhpVulnerablePathsInspection inspection into the analysis scope:

  include:
    - name: PhpVulnerablePathsInspection
  

Alternatively, you can use the inspections section of qodana.yaml:

  inspections:
    - inspection: PhpVulnerablePathsInspection
      enabled: true
  

In the qodana.yaml file, include the JvmTaintAnalysis inspection into the analysis scope:

  include:
    - name: JvmTaintAnalysis
  

Alternatively, you can use the inspections section of qodana.yaml:

  inspections:
    - inspection: JvmTaintAnalysis
      enabled: true
  

Configure the vulnerability checker

To start using the Vulnerability checker feature, enable the VulnerableLibrariesGlobal inspection:

include:
  - name: VulnerableLibrariesGlobal

Manage plugins

You can specify the plugins that will be downloaded and invoked during inspection.

plugins:
  - id: <plugin.id>

Here, <plugin-id> denotes the Plugin ID from JetBrains Marketplace. For example, for Grazie Professional the Plugin ID will be com.intellij.grazie.pro. To find the Plugin ID, on the plugin page click the Overview tab and then navigate to the Additional Information section.

Plugin cache is stored in the /data/cache/plugins directory.

To install third-party software required for your plugins, you can:

Use the bootstrap key
Develop your custom Dockerfile that starts with FROM jetbrains/qodana.... You can use Qodana Dockerfile examples available on GitHub.

Last modified: 11 December 2024