Qodana 2025.1 Help

Deployment

This section describes all deployment options available for Qodana.

Native mode

By default, Qodana runs its linters using Docker based on Linux images. In specific cases, you have to deal with private packages or run Qodana on the operating systems that provide incomplete support for Docker.

To overcome this, Qodana supports native mode for the Qodana for JVM, Qodana Community for JVM, Qodana for PHP, Qodana for JS, and Qodana for .NET linters. You can run native mode on Linux, macOS, and Microsoft Windows.

In this case, Qodana reuses its execution environment, which lets you execute Qodana in exactly the same environment as you use for building the projects, use the correct operating system, have access to all repository credentials, and resolve dependencies.

Before you start

General steps for all supported linters

In your operating system, save the QODANA_TOKEN environment variable containing the Qodana Cloud project token.

If you wish to run Qodana using a command line, then install Qodana CLI on the machine where you will run it.

Starting from version 2023.3 of Qodana, the sanity inspection will report in case the qodana.yaml file containing the bootstrap key is missing in your project directory. You can disable this inspection using the --disable-sanity option, or add this inspection to a baseline.

Qodana for .NET

In addition to general steps, make sure that you have a proper version of the .NET SDK and all required dependencies installed on your machine.

Build the project before inspecting it using Qodana. You can do it by using the bootstrap key of the qodana.yaml file. The project building and artifact packaging stages should occur before Qodana or simultaneously with it. Because running Qodana may affect the project state and its files, it is advised to avoid reusing the same directory in your build pipelines any further.

You can also provide Qodana a pre-built project, or specify the build steps in your CI/CD pipeline. To remove warnings related to project building, in your repository create the empty qodana.yaml file.

How it works

You can enable native mode by using the ide option in the qodana.yaml file:

ide: <linter>

This table contains the list of <linter> values:

This configuration tells Qodana to download and employ the required JetBrains IDE binary file while running the Qodana linter.

Below are the examples showing how you can run Qodana in native mode:

  1. Make sure that the QODANA_TOKEN variable is defined in the environment and refers to a proper project token. If necessary, you can define it:

    QODANA_TOKEN=<cloud-project-token>
  2. If you have already enabled native mode using the qodana.yaml file, use this command:

    qodana scan

    You can also run Qodana without configuring the qodana.yaml file:

    qodana scan \    --ide <linter>

If you have already enabled native mode using the qodana.yaml file, you can use a basic configuration sample from the GitHub Actions section.

To run Qodana without configuring the qodana.yaml file, in your GitHub repository navigate to a workflow configuration file and specify the --ide,<linter> option:

name: Qodana on: workflow_dispatch: pull_request: push: branches: - master - 'releases/*' jobs: qodana: runs-on: ubuntu-latest permissions: contents: write pull-requests: write checks: write steps: - uses: actions/checkout@v3 with: ref: ${{ github.event.pull_request.head.sha }} # to check out the actual pull request commit, not the merge commit fetch-depth: 0 # a full history is required for pull request analysis - name: 'Qodana Scan' uses: JetBrains/qodana-action@v2025.1 with: args: --ide,<linter> env: QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}

IDE integration

You can run Qodana in several JetBrains IDEs, Visual Studio Code, and Visual Studio. See the Overview of IDE Integration section for details.

Qodana CLI

Qodana CLI is a simple cross-platform command-line tool that lets you run Qodana linters with minimum effort.

To run Qodana CLI in the default mode, you must have Docker or Podman installed and running locally. If you are using Linux, you should be able to run Docker under your current non-root user.

  1. Install Qodana CLI on your machine using available options:

    Install with Homebrew (recommended):

    brew install jetbrains/utils/qodana

    Alternatively, you can install Qodana CLI using our installer:

    curl -fsSL https://jb.gg/qodana-cli/install | bash

    You can install a nightly or any other version the following way:

    curl -fsSL https://jb.gg/qodana-cli/install | bash -s -- nightly

    On Linux, you can also install Qodana using Go:

    go install github.com/JetBrains/qodana-cli@latest

    Install with Windows Package Manager (recommended):

    winget install -e --id JetBrains.QodanaCLI

    Install with Chocolatey:

    choco install qodana

    Install with Scoop:

    scoop bucket add jetbrains https://github.com/JetBrains/scoop-utils scoop install qodana
  2. In the project root directory, declare the QODANA_TOKEN variable containing a project token:

    QODANA_TOKEN=<cloud-project-token>
    set QODANA_TOKEN=<cloud-project-token>
  3. Run Qodana:

    qodana scan
    qodana scan

Docker images

Qodana is distributed across multiple Docker images. Essentially, the names of these Docker images are similar to the names of the linters. Details and configuration examples are available in the Overview of linters section and other sections dedicated to specific linters referenced from that section.

CI integration

You can run Qodana using various CI/CD pipelines, as explained in the Overview of CI integration section.

For Azure Pipelines, CircleCI, GitHub Actions, GitLab CI/CD, and TeamCity, Qodana provides native solutions. To run Qodana using Bitbucket Cloud, Jenkins, and Space Automation, you can use Docker images.

Gradle plugin

The Gradle Qodana plugin provides the Gradle interface for running code inspections provided by Qodana. To start, apply the Gradle plugin org.jetbrains.qodana in the Gradle configuration file.

Add the following to the build.gradle configuration file.

plugins { id "org.jetbrains.qodana" version "<plugin-version>" }

Add the following to the build.gradle.kts configuration file:

plugins { id("org.jetbrains.qodana") version "<plugin-version>" }

qodana { } extension configuration

Properties available for configuration in the qodana { } top-level configuration closure:

Name

Description

Type

Default Value

projectPath

Path to the project folder to analyze.

String

project.projectDir

resultsPath

Path to the directory to store task results.

String

"${projectPath}/build/qodana/results"

cachePath

Path to the directory to store the generated report.

String

"${projectPath}/build/qodana/cache/"

Gradle Qodana Tasks

qodanaScan

Start Qodana in the project directory.

The task relies on the qodana { } extension configuration. However, it is also controlled by provided arguments.

Example

Add this to your Gradle configuration file:

  • Groovy – build.gradle

    plugins { // applies Gradle Qodana plugin to use it in project id "org.jetbrains.qodana" version "..." } qodana { // by default result path is $projectPath/build/results resultsPath = "some/output/path" } qodanaScan { arguments = ["--fail-threshold", "0"] }
  • Kotlin – build.gradle.kts

    plugins { // applies Gradle Qodana plugin to use it in a project id("org.jetbrains.qodana") version "..." } qodana { // by default, the result path is $projectPath/build/results resultsPath.set("some/output/path") } qodanaScan { resultsPath.set("some/output/path") arguments.set(listOf("--fail-threshold", "0")) }

Now you can run analyses using the qodanaScan Gradle task:

gradle qodanaScan // or ./gradlew qodanaScan

A complete guide for options and configuration of arguments parameters can be found on Qodana CLI docs page.

Last modified: 28 May 2025