Qodana 2023.1 Help

GitHub Actions

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

Prepare your project

You may need to grant GitHub permissions for running Qodana Scan as shown below.

  1. In your repository, navigate to Settings | Actions | General.

  2. In the Actions permissions section, click Allow <repository-owner>, and select non-<repository-owner>, actions and reusable workflows.

  3. In the Allow specified actions and reusable workflows field, specify JetBrains/qodana-action@* and then click Save.

Allowing Qodana Scan on GitHub

Usage

Basic configuration

To configure Qodana Scan, save the .github/workflows/code_quality.yml file containing the workflow configuration:

name: Qodana on: workflow_dispatch: pull_request: push: branches: - main - 'releases/*' jobs: qodana: timeout-minutes: 15 runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 with: fetch-depth: 0 - name: 'Qodana Scan' uses: JetBrains/qodana-action@v2023.1.0

Using this workflow, Qodana will run on the main branch, release branches, and on the pull requests coming to your repository.

Here:

  • fetch-depth: 0 is required for checkout in case Qodana works in pull request mode (reports issues that appeared only in that pull request)

  • timeout-minutes specifies the timeout for running Qodana, which can be helpful especially if you run Qodana without cache

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

GitHub code scanning

You can set up GitHub code scanning for your project using Qodana. To do it, 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 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 enforce GitHub to block the merge of pull requests if the Qodana quality gate has failed. To do it, 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.

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

  2. Under your repository name, click Settings.

  3. On the left menu, click Branches.

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

  5. Add main to Branch name pattern.

  6. Select Require status checks to pass before merging.

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

  8. Click Create.

Quality gate and baseline

You can combine the quality gate, and baseline features to manage your technical debt, report only new problems, and block pull requests that contain too many issues.

Follow these steps to establish a baseline for your project:

  1. Run Qodana locally over your project:

cd <source-directory> qodana scan --show-report
  1. Open your report at http://localhost:8080/, add detected problems to the baseline, and download the qodana.sarif.json file.

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

  3. Append --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@v2023.1.0 with: args: --baseline,qodana.sarif.json

If you want to update the baseline, you must repeat these steps.

After that, the Qodana Scan GitHub action will generate alerts only for the problems that were not added to the baseline as new.

To establish a quality gate additionally to the baseline, add this line to qodana.yaml in the root of your repository:

failThreshold: <number-of-accepted-problems>

Based on this, you will be able to detect only new problems in pull requests that fall beyond the baseline. At the same time, pull requests with new problems exceeding the fail-threshold limit will be blocked, and the workflow will fail.

Qodana Cloud

To forward inspection results to Qodana Cloud, all you need to do is to specify the QODANA_TOKEN environment variable in the build configuration.

  1. In the GitHub UI, create the QODANA_TOKEN encrypted secret and save the project token as its value.

  2. In the GitHub workflow file, add QODANA_TOKEN variable to the env section of the Qodana Scan step:

- name: 'Qodana Scan' uses: JetBrains/qodana-action@v2023.1.0 env: QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}

After the token is set for analysis, all Qodana job results will be uploaded to your Qodana Cloud project.

Qodana Cloud

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.

  3. Copy the Markdown text to your repository README file.

Creating status badge

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 as an artifact to the job. Optional.

true

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-2023.1-${{ github.ref }}-${{ github.sha }}

additional-cache-key

Set the additional cache key. Optional.

qodana-2023.1-${{ 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

true

Last modified: 24 April 2023