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 Qodana Docker images within GitLab CI/CD pipelines and covers the following cases:

Inspecting specific branches and merge requests,
Exposing Qodana reports in the GitLab CI/CD user interface,
Using the quality gate and baseline features,
Generating Code Quality reports.

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 the root directory of your project, save the .gitlab-ci.yml file. This file will contain the pipeline configuration that will be used by GitLab CI/CD.

Basic configuration

This is the basic pipeline configuration.

qodana:
   image:
      name: jetbrains/qodana-<linter>
      entrypoint: [""]
   cache:
      - key: qodana-2024.3-$CI_DEFAULT_BRANCH-$CI_COMMIT_REF_SLUG
        fallback_keys:
           - qodana-2024.3-$CI_DEFAULT_BRANCH-
           - qodana-2024.3-
        paths:
           - .qodana/cache
   variables:
      QODANA_TOKEN: $qodana_token
   script:
      - qodana --cache-dir=$CI_PROJECT_DIR/.qodana/cache

This configuration contains the following keywords:

image:name pulls the Qodana Docker image of your choice,
cache configures GitLab caches to store the Qodana cache, so later runs will be faster,
script runs the qodana command and enumerates the Qodana configuration options described in the Shell commands section,
variables defines environment variables to be used. The QODANA_TOKEN variable refers to the project token generated in Qodana Cloud.

Inspect specific branches

Using the only keyword, you can tell Qodana which branches to inspect. To inspect only the main branch and incoming merge requests, you can use this configuration:

qodana:
   only:
      - main
      - merge_requests
   image:
      name: jetbrains/qodana-<linter>
      entrypoint: [""]
   cache:
      - key: qodana-2024.3-$CI_DEFAULT_BRANCH-$CI_COMMIT_REF_SLUG
        fallback_keys:
           - qodana-2024.3-$CI_DEFAULT_BRANCH-
           - qodana-2024.3-
        paths:
           - .qodana/cache
   variables:
      QODANA_TOKEN: $qodana_token
   script:
      - qodana --results-dir=$CI_PROJECT_DIR/.qodana/results --cache-dir=$CI_PROJECT_DIR/.qodana/cache

Expose Qodana reports

To make a report available in any given merge request without using Qodana Cloud, you can use the artifacts expose_as keywords and change the path to the artifacts:

qodana:
   image:
      name: jetbrains/qodana-<linter>
      entrypoint: [""]
   cache:
      - key: qodana-2024.3-$CI_DEFAULT_BRANCH-$CI_COMMIT_REF_SLUG
        fallback_keys:
           - qodana-2024.3-$CI_DEFAULT_BRANCH-
           - qodana-2024.3-
        paths:
           - .qodana/cache
   variables:
      QODANA_TOKEN: $qodana_token
   script:
      - qodana --save-report --results-dir=$CI_PROJECT_DIR/.qodana/results
         --cache-dir=$CI_PROJECT_DIR/.qodana/cache
   artifacts:
      paths:
         - .qodana/results/
      expose_as: 'Qodana report'

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 use the --fail-threshold <number> and --baseline <path/to/qodana.sarif.json> lines in the script block to invoke the quality gate and baseline features.

qodana:
   image:
      name: jetbrains/qodana-<linter>
      entrypoint: [""]
   cache:
      - key: qodana-2024.3-$CI_DEFAULT_BRANCH-$CI_COMMIT_REF_SLUG
        fallback_keys:
           - qodana-2024.3-$CI_DEFAULT_BRANCH-
           - qodana-2024.3-
        paths:
           - .qodana/cache
   variables:
      QODANA_TOKEN: $qodana_token
   script:
      - qodana --fail-threshold <number> --baseline <path/to/qodana.sarif.json> --results-dir=$CI_PROJECT_DIR/.qodana/results
         --cache-dir=$CI_PROJECT_DIR/.qodana/cache
   artifacts:
      paths:
         - .qodana/results/
      expose_as: 'Qodana report'

Generate 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. To configure this, to the artifacts block of the GitLab CI/CD configuration add the codequalitykeyword and specify the path to the gl-code-quality-report.json file, for example:

   image:
        name: jetbrains/qodana-<linter>
        entrypoint: [""]
   cache:
       - key: qodana-2024.3-$CI_DEFAULT_BRANCH-$CI_COMMIT_REF_SLUG
         fallback_keys:
             - qodana-2024.3-$CI_DEFAULT_BRANCH-
             - qodana-2024.3-
         paths:
             - .qodana/cache
   variables:
       QODANA_TOKEN: $qodana_token
   script:
       - qodana --results-dir=$CI_PROJECT_DIR/.qodana/results
           --cache-dir=$CI_PROJECT_DIR/.qodana/cache
   artifacts:  
       reports:
           codequality: .qodana/results/gl-code-quality-report.json # Path to the report

Last modified: 05 March 2025