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
Forwarding inspection reports to Qodana Cloud
Exposing Qodana reports in the GitLab CI/CD user interface
Using the quality gate and baseline features
Generating Code Quality reports

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

In this configuration, the image:name keyword pulls the Qodana Docker image of your choice.

The cache keyword configures GitLab caches to store the Qodana cache, so later runs will be faster.

The script keyword runs the qodana command and enumerates the Qodana configuration options described in the Shell commands section.

The variables keyword defines environment variables to be used. The QODANA_TOKEN variable refers to the project token generated in Qodana Cloud. This token is required by the paid Qodana linters, and is optional for using with the Community linters. If you are using a Qodana Cloud instance other than https://qodana.cloud/, override it by declaring the QODANA_ENDPOINT environment variable.

You can see these sections to learn how to generate the project token:

The project setup section explains how to get the project token generated while first working with Qodana Cloud
The Manage a project section explains how to create a project in the existing Qodana Cloud organization

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: 23 January 2025