CircleCI

CircleCI is a cloud-based CI/CD system. You can build Qodana into your CircleCI pipelines using the CircleCI Qodana orb as described in this section.

Before you start

Qodana Cloud

All configuration examples in this section use a project token generated by Qodana Cloud. This token is required for the paid Qodana linters and optional for use with the Community linters. You can see these sections to learn how to generate the project token in the Qodana Cloud UI:

The project setup section explains how to generate a project token when first working with Qodana Cloud.
The Manage a project section explains how to create a project token within an existing Qodana Cloud organization.

Once you obtain the project token, you can use the QODANA_TOKEN variable for identifying in a pipeline or workflow.

If you are using a Qodana Cloud instance other than https://qodana.cloud/, override it by setting the QODANA_ENDPOINT environment variable.

Prepare your project

In your CircleCI organization settings, navigate to the Contexts section and define the qodana context.
In the Contexts section, click the qodana context. In this context, define the QODANA_TOKEN environment variable and save the project token as its value.
In your CircleCI organization settings, navigate to the Security section. In this section, opt in to allow using uncertified public orbs.
If necessary, in your repository create the .circleci/config.yml file that will contain a CircleCI configuration.

Basic configuration

In the .circleci/config.yml file, save the following configuration:

version: 2.1

orbs:
  qodana: jetbrains/qodana@2025.2

jobs:
  code-quality:
    machine:
      image: 'ubuntu-2004:current'
    environment: $QODANA_TOKEN
    steps:
      - checkout
      - qodana/scan

workflows:
  main:
    jobs:
      - code-quality:
          context: qodana

This table describes configuration elements:

Configuration block	Description
`orbs`	Invokes the CircleCI Qodana orb and configures its version
`jobs`	Refers to the `QODANA_TOKEN` variable defined in the Prepare your project chapter
`workflows`	Invokes the `qodana` context that contains the `QODANA_TOKEN` variable

This configuration will be extended in the sections below.

Baseline and quality gate

This configuration uses the args parameter to invoke the baseline and quality gate features:

version: 2.1

orbs:
  qodana: jetbrains/qodana@2025.2

jobs:
  code-quality:
    machine:
      image: 'ubuntu-2004:current'
    environment: $QODANA_TOKEN
    steps:
      - checkout
      - qodana/scan:
          args: > # Use space to separate arguments
            --baseline <path-relative-to-project-dir>
            --fail-threshold <number-of-problems> 

workflows:
  main:
    jobs:
      - code-quality:
          context: qodana

Specific linter

This configuration sample uses the args parameter to run the specific linter like jetbrains/qodana-jvm:

version: 2.1

orbs:
  qodana: jetbrains/qodana@2025.2

jobs:
  code-quality:
    machine:
      image: 'ubuntu-2004:current'
    environment: $QODANA_TOKEN
    steps:
      - checkout
      - qodana/scan:
          args: -l jetbrains/qodana-jvm # Use space to separate arguments

workflows:
  main:
    jobs:
      - code-quality:
          context: qodana

Specific branch

This configuration instructs Qodana to analyze changes only on the main branch:

version: 2.1

orbs:
  qodana: jetbrains/qodana@2025.2

jobs:
  code-quality:
    machine:
      image: 'ubuntu-2004:current'
    environment: $QODANA_TOKEN
    steps:
      - checkout
      - qodana/scan

workflows:
  main:
    jobs:
      - code-quality:
          context: qodana
          filters:
            branches:
              only:
                - main  # Specify your branch here 

Commands and parameters

The CircleCI Qodana orb provides the scan command to let you analyze your project and report the results.

This table contains the list of optional string parameters that can be additionally used with the scan command.

Parameter	Description	Default value
`primary-cache-key`	Customize the generated cache hash	`qodana-2025.2-<< pipeline.git.branch >>-<< pipeline.git.revision >>`
`additional-cache-key`	Customize the generated cache hash	`qodana-2025.2-<< pipeline.git.branch >>`
`args`	Additional arguments of the Qodana CLI `scan` command	No default value
`artifact-name`	Name of the analysis artifact, used for uploading analysis results	`qodana-report`
`cache-dir`	Directory for Qodana caches	`/tmp/cache/qodana`
`results-dir`	Directory for storing the results of scanning	`/tmp/qodana/results`

07 August 2025