Quality gate

Quality gate is the maximum number of problems that can be detected by Qodana without causing a CI/CD workflow or pipeline fail. Once the quality gate limit is reached, Qodana terminates with exit code 255.

This feature lets you control your code quality and build software that meets your quality metrics. For example, if you set a quality gate for ten problems, a build workflow will fail once the eleventh problem is detected.

The quality gate and fail threshold terms are used interchangeably with the former being a feature in overall, and the latter meaning a configuration option.

This feature is supported by all linters available under Community, Ultimate, and Ultimate Plus licenses and their trial versions.

This section explains how to configure a quality gate for:

Local run using a Docker or Qodana CLI command
GitHub actions
Jenkins
Gitlab CI/CD

Local run

You can run Qodana locally with the configured quality gate using either the Qodana CLI tool or available Docker images:

qodana scan \
   -e QODANA_TOKEN="<cloud-project-token>" \
   --fail-threshold <number>

In this command, the --fail-threshold <number> option configures the quality gate. The QODANA_TOKEN variable refers to the project token required by the Ultimate and Ultimate Plus linters.

docker run \
   -v <source-directory>/:/data/project/  \
   -e QODANA_TOKEN="<cloud-project-token>" \
   jetbrains/qodana-<linter> \
   --fail-threshold <number>

In this command, <source-directory> is the full local path to the project source code, and the --fail-threshold <number> option configures the quality gate. The QODANA_TOKEN variable refers to the project token required by the Ultimate and Ultimate Plus linters.

GitHub Actions

You can enforce GitHub to block merge of pull requests if the quality gate has failed. To do it, create a branch protection rule as described below:

Create a new or open an existing GitHub Actions workflow that invokes the Qodana scan action.
Set the workflow to run on pull_request events that target the main branch.
name: Qodana on: pull_request: branches: - main jobs: qodana: runs-on: ubuntu-latest permissions: contents: write pull-requests: write checks: write steps: - uses: actions/checkout@v3 with: ref: ${{ github.event.pull_request.head.sha }} # to check out the actual pull request commit, not the merge commit fetch-depth: 0 # a full history is required for pull request analysis - name: 'Qodana Scan' uses: JetBrains/qodana-action@v2023.2 env: QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}
Instead of main, you can specify your branch here. The QODANA_TOKEN variable refers to the project token required by the Ultimate and Ultimate Plus linters.
Set the fail threshold (number) for the Qodana Action fail-threshold option.
Under your repository name, click Settings.
On the left menu, click Branches.
In the branch protection rules section, click Add rule.
Add main to Branch name pattern.
Select Require status checks to pass before merging.
Search for the Qodana status check, then check it.
Click Create.

Jenkins

To set up a quality gate in a Jenkins Pipeline, you can add the --fail-threshold <number> option to the steps block:

pipeline {
   environment {
      QODANA_TOKEN=credentials('qodana-token')
    }
   agent {
      docker {
         args '''
            -v <path-to-project>:/data/project
            --entrypoint=""
         '''
         image 'jetbrains/qodana-<linter>'
      }
   }
   stages {
      stage('Qodana') {
         steps {
            sh '''
               qodana \
               --fail-threshold <number>
            '''
         }
      }
   }
}

The QODANA_TOKEN variable in this snippet refers to the project token contained in the qodana-token credentials and required by the Ultimate and Ultimate Plus linters.

GitLab CI/CD

To run a quality gate in a GitLab CI/CD pipeline, you can save this configuration to the .gitlab-ci.yml file:

qodana:
 image:
   name: jetbrains/qodana-<linter>
   entrypoint: ['']
variables:
   QODANA_TOKEN: $qodana_token
script:
   - qodana --fail-threshold <number>
 artifacts:
   paths:
     - qodana

In this sample, the script section specifies the --fail-threshold <number> option. The QODANA_TOKEN variable in this snippet refers to the project token and required by the Ultimate and Ultimate Plus linters.

Last modified: 02 November 2023