GitLab CI/CD

GitLab CI/CD is a tool for software development that uses various CI/CD methodologies. This section explains how you can run the Qodana Scan GitLab Pipeline component.

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

Make sure that your project repository is accessible to GitLab CI/CD.

In GitLab CI/CD UI, create the following environment variables:

Variable name	Description
`QODANA_TOKEN`	Generated project token. Save it in the GitLab CI/CD UI as described on the GitLab CI/CD website. Also, make sure that the variable is not marked as protected and the Expand variable reference flag is enabled.
`QODANA_GITLAB_TOKEN`	A personal access token or a project access token required for Quick-Fixes and summary reports as comments in merge requests. The holder of a personal access token will be shown as an author for all Qodana actions, so it is advised to use a project access token. For Quick-Fixes, enable the `api` and `write_repository` permissions while configuring access tokens.

Variable name

Description

QODANA_TOKEN

Generated project token. Save it in the GitLab CI/CD UI as described on the GitLab CI/CD website. Also, make sure that the variable is not marked as protected and the Expand variable reference flag is enabled.

QODANA_GITLAB_TOKEN

A personal access token or a project access token required for Quick-Fixes and summary reports as comments in merge requests. The holder of a personal access token will be shown as an author for all Qodana actions, so it is advised to use a project access token.

For Quick-Fixes, enable the api and write_repository permissions while configuring access tokens.

In the root directory of your project, save the .gitlab-ci.yml file. This file will contain a pipeline configuration that will be used by GitLab CI/CD.

Argument notation

Qodana supports the Shell-like notation for specifying arguments, where a space separates keys and values and single and double quotes are used to enclose the values. This is the recommended method of specifying arguments while configuring Qodana.

This table contains examples of both notations:

Example	Actual notation	Legacy notation
Single argument	--profile-name qodana.starter	--profile-name,qodana.starter
Two arguments	--fail-threshold 10 --property key=value	--fail-threshold,10 --property,key=value
Using quotation with values containing space characters	--property "key=some value"	--property,"key=some value"

For backward compatibility, the old comma-separated notation is still supported; however, it is deprecated and will be removed in the future version of Qodana.

Basic configuration

To run Qodana in container mode, in the cloud-based GitLab CI/CD version, save the following snippet to the .gitlab-ci.yml file:

         include:
            - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
              inputs:
                 image: jetbrains/qodana-<image>:<version>
      

Here, the inputs:image argument specifies the Docker image that you would like to employ.

         include:
            - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
              inputs:
                 os: windows | mac
                 args: --image jetbrains/qodana-<image>:<version>
      

This configuration uses the inputs:os argument to specify the operating system.

To run Qodana in native mode, use the following configuration snippets:

         include:
            - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
              inputs:
                 image: <my-custom-docker-image>
                 args: --linter <linter> 
      

Here, the inputs:image specifies a custom Docker image to run Qodana inside, while the inputs:args argument configures the Qodana linter.

         include:
            - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
              inputs:
                 os: windows | mac
                 args: --linter <linter> --within-docker false
      

Here, the inputs:args argument configures the Qodana linter.

All these configurations include the Qodana Scan GitLab Pipeline component and enables caches, Code Quality report generation, merge request analysis, and comments to merge requests. You can override these settings using descriptions from the sections below and the Configuration chapter. The --image argument specifies a Qodana image in case of Windows or macOS.

The included component creates the qodana job that can be configured as any other job in GitLab CI/CD. You can view the predefined configuration of this job using our template.

For example, this code snippet lets define before_script, change job execution rules, and add an environmental variable.

include:
  - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
    inputs:
       image: jetbrains/qodana-<image>:<version>

some-task:
  stage: test
  script:
    - echo "I am complete!"
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

qodana:
  before_script:
    - echo "Qodana job starts..."
  needs:
    - some-task
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

For the on-premise version of GitLab CI/CD, in the .gitlab-ci.yml file save the following configuration:

include:
   - component: $CI_SERVER_FQDN/<org>/<repo>/qodana-gitlab-ci@v2026.1
     inputs:
        image: jetbrains/qodana-<linter>:<version> | <any-custom-docker-image>

In this snippet, qodana-gitlab-ci is the GitLab CI/CD component described on the GitLab CI/CD website.

Configure cache

By default, caching is enabled in Qodana with the following keys:

      - key: qodana-2026.1-$CI_DEFAULT_BRANCH-$CI_COMMIT_REF_SLUG
        fallback_keys:
           - qodana-2026.1-$CI_DEFAULT_BRANCH-
           - qodana-2026.1-

If you wish to override the default cache settings, use this configuration:

include:
   - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
     inputs:
        image: jetbrains/qodana-<linter>:<version> | <any-custom-docker-image>

qodana:
   cache:
      - key: qodana-2026.1-$CI_DEFAULT_BRANCH-$CI_COMMIT_REF_SLUG
        fallback_keys:
           - qodana-2026.1-$CI_DEFAULT_BRANCH-
           - qodana-2026.1-
        paths:
           - $[[ inputs.cache-dir ]]

Override an operating system

By default, Qodana is configured for Linux. You can override an operating system using the os keyword. For example, you can use the following configuration for Microsoft Windows:

include:
   - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
     inputs:
        os: windows
        args: --image jetbrains/qodana-<image>:<version>

Specific branches

By default, Qodana is configured for analyzing the master and main branches, release branches and merge requests meaning that you do not have to provide any additional configurations and use the basic configuration.

If you wish to override this behavior, you can modify the following configuration:

include:
   - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
     inputs:
        image: jetbrains/qodana-<image>:<version>

qodana:
  rules:
     # GIT_DEPTH: 0 is required for checkout in case Qodana works in merge request mode 
     # (reports issues that appeared only in that merge request)
     - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $QODANA_MR_MODE == "true"
       variables:
          GIT_DEPTH: 0
     # run analysis in case of merge request
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
     # restrict branch analysis only to main/master and release branches
     - if: $CI_COMMIT_BRANCH =~ /^releases/ || $CI_COMMIT_BRANCH == "master" || $CI_COMMIT_BRANCH == "main"
        # mr-mode does not make any sense for branch analysis
       variables:
          QODANA_MR_MODE: false

The rules block of this configuration tells Qodana what branches to inspect.

Quick-Fixes

Choose the Quick-Fix strategy using either of two configuration methods:
# Possible values: apply | cleanup fixesStrategy: apply
# Possible values: --apply-fixes | --cleanup args: --apply-fixes
Depending on your needs, in the pipeline configuration define the push-fixes property:
Save this configuration to create a new branch with fixes and a merge request to the original branch:
push-fixes: merge-request
Save this configuration to push fixes to the original branch:
push-fixes: branch

Here is an example configuration that uses the inputs block for configuring the pipeline:

include:
   - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
     inputs:
        image: jetbrains/qodana-<image>:<version>
        push-fixes: merge-request
        args: --apply-fixes

Expose Qodana reports

To make a report available in any given merge request without using Qodana Cloud, you can use the upload-result keyword and specify the artifact name using the artifact-name keyword, for example:

include:
   - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
     inputs:
        upload-result: true
        artifact-name: Qodana report
        image: jetbrains/qodana-<image>:<version>

Assuming that you have configured your pipeline similarly, this is what it may look like:

Qodana report affiliated with a pipeline in a merge request
Available actions for a given exposed Qodana artifact

Quality gate and baseline

You can employ the --fail-threshold <number> and --baseline <path/to/qodana.sarif.json> lines in the inputs:args block to run the quality gate and baseline features.

include:
   - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
     inputs:
        image: jetbrains/qodana-<image>:<version>
        args: |
            --baseline qodana.sarif.json 
            --fail-threshold <number-of-accepted-problems>

Code Quality reports

Starting from version 2024.1 of Qodana, you can use the merge request UI of GitLab CI/CD to view specific lines of code that contain problems along with their description and recommendations for improvement.

To implement this feature, Qodana generates JSON-formatted analysis reports supported by Code Quality and contained in the gl-code-quality-report.json file.

By default, this feature is configured to true, so you do not need to make any additional settings. If necessary, you can override a path to reports using the codequality option:

include:
   - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
     inputs:
        image: jetbrains/qodana-<image>:<version>

qodana:
   artifacts:
      reports:
         codequality: $QODANA_RESULTS_DIR/gl-code-quality-report.json

Qodana logs

Use the following configuration to get log data from Qodana on GitLab CI/CD:

include:
   - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
     inputs:
        image: jetbrains/qodana-<image>:<version>
        upload-result: true
        results-dir: $CI_PROJECT_DIR/.qodana/results

qodana:
   artifacts:
      paths:
         - .qodana/results/
      expose_as: 'Qodana report'
      when: always

This configuration uses the .qodana/results directory for generating logs and then exposes this directory as an artifact.

To upload logs from a Qodana job that fails with a timeout, add the RUNNER_SCRIPT_TIMEOUT variable with a value less than a pipeline timeout:

include:
   - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2026.1
     inputs:
        image: jetbrains/qodana-<image>:<version>
        upload-result: true
        results-dir: $CI_PROJECT_DIR/.qodana/results

qodana:
   timeout: <specify timeout>
   variables:
      RUNNER_SCRIPT_TIMEOUT: <specified timeout value minus 5 minutes>
   artifacts:
      paths:
         - .qodana/results/
      expose_as: 'Qodana report'
      when: always

The details are available on the GitLab CI/CD website.

Configuration

This table contains the list of options that can be configured using the inputs block:

Name	Description	Default Value
`stage`	CI stage for Qodana execution	`test`
`job-name`	A Qodana job name. Could be used to customize the order of running several Qodana jobs within the same pipeline	`qodana`
`args`	Additional Qodana CLI `scan` command arguments, split the arguments with commas (`,`), for example `-i,frontend,--print-problems`. Optional.	-
`results-dir`	Directory to store the analysis results relative to the project root. Optional.	`$CI_PROJECT_DIR/.qodana/results`
`upload-result`	Upload Qodana results (SARIF, other artifacts, logs) as an artifact to the job. Optional.	`false`
`artifact-name`	Specify Qodana results artifact name, used for result uploading. Optional.	`Qodana report`
`cache-dir`	Directory to store Qodana cache relative to the project root. Optional.	`$CI_PROJECT_DIR/.qodana/caches`
`use-caches`	Utilize GitHub caches for Qodana runs. Optional.	`true`
`code-quality-report`	Use Code Quality report produced by Qodana	`true`
`mr-mode`	Analyze ONLY changed files in a merge request. Optional.	`true`
`post-mr-comment`	Post a comment with a Qodana results summary to a merge request. Optional.	`true`
`push-fixes`	Push Qodana fixes to the repository, can be `none`, `branch` to the current branch, or `merge-request`. Optional.	`none`
`commit-message`	Commit message used when Quick-Fixes are applied	`Apply quick-fixes by Qodana`
`os`	Operating system used for running pipelines, required for pre-configuration. Could accept the `linux`, `windows` or `mac` values	`linux`
`image`	Linux-only option. The image used for job execution. Required since version 2026.1	`docker:27.5.1`
`windows-tags`	Windows-only option. Custom runner tags used for the job	`- saas-windows-medium-amd64`
`mac-tags`	macOS-only option. Custom runner tags used for the job	`- saas-macos-medium-m1`

25 March 2026