Qodana 2024.3 Help

GitHub Actions

The Qodana Scan GitHub action allows you to run Qodana in a GitHub repository.

Prepare your project

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.

Basic configuration

  1. On the Settings tab of the GitHub UI, create the QODANA_TOKEN encrypted secret and save the project token as its value. If you are using a Qodana Cloud instance other than https://qodana.cloud/, override it by declaring the QODANA_ENDPOINT environment variable.

  2. On the Actions tab of the GitHub UI, set up a new workflow and create the .github/workflows/code_quality.yml file.

  3. To inspect the main and master branches, as well as release branches and the pull requests coming to your repository, save this workflow configuration to the .github/workflows/code_quality.yml file:

    name: Qodana on: workflow_dispatch: pull_request: push: branches: # Specify your branches here - main # The 'main' branch - master # The 'master' branch - 'releases/*' # The release branches 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@v2024.3 env: QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}

We recommend that you have a separate workflow file for Qodana because different jobs run in parallel

Quick-fixes

To automatically fix issues found by Qodana and push the changes to your repository, follow the procedure below.

  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, configure the push-fixes option of your workflow configuration:

    Save this configuration to create a new branch with fixes and a pull request to the original branch:

    push-fixes: pull-request

    Also, enable GitHub Actions to create and approve pull requests.

    Save this configuration to push fixes to the original branch:

    push-fixes: branch pr-mode: false
  3. Set the correct permissions for the job, for example:

    permissions:   contents: write   pull-requests: write   checks: write

This is an example configuration snippet containing all options:

permissions: contents: write pull-requests: write checks: write steps: - name: 'Qodana Scan' uses: JetBrains/qodana-action@v2024.3 with: args: --apply-fixes push-fixes: pull-request env: QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}

GitHub code scanning

You can set up GitHub code scanning for your project using Qodana. To do this, add these lines to the code_quality.yml workflow file right below the basic configuration of Qodana Scan:

- uses: github/codeql-action/upload-sarif@v2 with: sarif_file: ${{ runner.temp }}/qodana/results/qodana.sarif.json

This sample invokes the codeql-action for uploading a SARIF-formatted Qodana report to GitHub, and specifies the report file using the sarif_file key.

Pull request quality gate

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

  1. Create a new or open an existing GitHub workflow that invokes the Qodana Scan action.

  2. Set the workflow to run on pull_request events that target the main branch:

    on: pull_request: branches: - main

    Instead of main, you can specify your branch here.

  3. Set the number of problems (integer) for the Qodana action fail-threshold option.

  4. Under your repository name, click Settings.

  5. On the left menu, click Branches.

  6. In the branch protection rules section, click Add rule.

  7. Add main to Branch name pattern.

  8. Select Require status checks to pass before merging.

  9. Search for the Qodana status check, then check it.

  10. Click Create.

Baseline and quality gate

Baseline

Follow these steps to establish a baseline for your project:

  1. Run Qodana locally on your project:

    cd project qodana scan \ -e QODANA_TOKEN="<cloud-project-token>"
  2. In Qodana Cloud, add detected problems to the baseline and then download the qodana.sarif.json file.

  3. Upload the qodana.sarif.json file to your project root on GitHub.

  4. Append the --baseline,qodana.sarif.json argument to the Qodana Scan action configuration args parameter in the code_quality.yml file:

    - name: Qodana Scan uses: JetBrains/qodana-action@main with: args: --baseline,qodana.sarif.json

To update your baseline, you need to repeat these steps once more.

From this point onward, GitHub will generate alerts only for problems that were not included in the baseline as new issues.

Quality gate

To establish a quality gate, in the workflow configuration specify the --fail-threshold option:

- name: Qodana Scan uses: JetBrains/qodana-action@v2024.3 with: args: --fail-threshold,<number-of-accepted-problems> env: QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}

Combined configuration

You can combine the baseline and quality gate features to manage your technical debt, report only new problems, and block pull requests that contain too many problems. Using this configuration, you will be able to detect only new problems in pull requests that fall beyond the baseline.

- name: Qodana Scan uses: JetBrains/qodana-action@v2024.3 with: args: --baseline,qodana.sarif.json,--fail-threshold,<number-of-accepted-problems> env: QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}

At the same time, pull requests with new problems exceeding the --fail-threshold limit will be blocked, and the workflow will fail.

Get a Qodana badge

You can set up a Qodana workflow badge in your repository, to do it, follow these steps:

  1. Navigate to the workflow run that you previously configured.

  2. On the workflow page, select Create status badge.

    Creating status badge
  3. Copy the Markdown text to your repository README file.

Configuration

Most likely, you won't need other options than args: all other options can be helpful if you are configuring multiple Qodana Scan jobs in one workflow.

Use with to define any action parameters:

with: args: --baseline,qodana.sarif.json cache-default-branch-only: true

Name

Description

Default Value

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. Optional.

${{ runner.temp }}/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 results uploading. Optional.

qodana-report

cache-dir

Directory to store Qodana cache. Optional.

${{ runner.temp }}/qodana/caches

use-caches

Utilize GitHub caches for Qodana runs. Optional.

true

primary-cache-key

Set the primary cache key. Optional.

qodana-2024.3-${{ github.ref }}-${{ github.sha }}

additional-cache-key

Set the additional cache key. Optional.

qodana-2024.3-${{ github.ref }}

cache-default-branch-only

Upload cache for the default branch only. Optional.

false

use-annotations

Use annotation to mark the results in the GitHub user interface. Optional.

true

pr-mode

Analyze ONLY changed files in a pull request. Optional.

true

post-pr-comment

Post a comment with the Qodana results summary to the pull request. Optional.

true

github-token

GitHub token to access the repository: post annotations, comments. Optional.

${{ github.token }}

push-fixes

Push Qodana fixes to the repository, can be none, branch to the current branch, or pull-request. Optional.

none

Last modified: 05 March 2025