Qodana 2025.1 Help

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.

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.

Basic configuration

In the .gitlab-ci.yml file, save the following configuration to include the Qodana Scan GitLab Pipeline component:

include: - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2025.1 inputs: args: --linter,<linter>

This configuration already 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 --linter argument specifies the linter that you would like to employ.

Configure cache

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

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

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

include: - component: $CI_SERVER_FQDN/qodana/qodana/qodana-gitlab-ci@v2025.1 inputs: args: --linter,<linter> qodana: cache: - key: qodana-2025.1-$CI_DEFAULT_BRANCH-$CI_COMMIT_REF_SLUG fallback_keys: - qodana-2025.1-$CI_DEFAULT_BRANCH- - qodana-2025.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@v2025.1 inputs: os: windows args: --linter,<linter>

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@v2025.1 inputs: args: --linter,<linter> 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

  1. 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
  2. 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@v2025.1 inputs: push-fixes: merge-request args: | --apply-fixes, --linter,<linter>

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@v2025.1 inputs: upload-result: true artifact-name: Qodana report args: --linter,<linter>

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

  1. Qodana report affiliated with a pipeline in a merge request

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

    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@v2025.1 inputs: args: | --baseline,qodana.sarif.json, --fail-threshold,<number-of-accepted-problems>, --linter,<linter>

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 inspection 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@v2025.1 inputs: args: --linter,<linter> qodana: artifacts: reports: codequality: $QODANA_RESULTS_DIR/gl-code-quality-report.json

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 or pr-mode

Analyze ONLY changed files in a merge request. Optional.

true

post-pr-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, merge-request or pull-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

Last modified: 14 May 2025