GitHub Actions

Usage

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

Basic configuration

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.
On the Actions tab of the GitHub UI, set up a new workflow and create the .github/workflows/code_quality.yml file.
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

Apply quick-fixes

To make Qodana automatically fix found issues and push the changes to your repository, you need to

Choose what kind of fixes to apply
- Specify fixesStrategy in the qodana.yaml file in your repository root
- Or set the action args property with the quick-fix strategy to use: --apply-fixes or --cleanup
Set push-fixes property to
- pull-request: create a new branch with fixes and create a pull request to the original branch
- or branch: push fixes to the original branch. Also, set pr-mode to false: currently, this mode is not supported for applying fixes.
Set the correct permissions for the job (contents: write, pull-requests: write, checks: write)
- If you use pull-request value for push-fixes property: allow GitHub Actions to create and approve pull requests

Example configuration:

- name: Qodana Scan
  uses: JetBrains/qodana-action@v2024.3
  with:
    pr-mode: false
    args: --apply-fixes
    push-fixes: pull-request
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

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 a quality gate has failed. To do it, create a branch protection rule as described below:

Create a new or open an existing GitHub workflow that invokes the Qodana Scan action.
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.

Set the number of problems (integer) 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.

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

Follow these steps to establish a baseline for your project:

Run Qodana locally over your project:

cd project
qodana scan \
   -e QODANA_TOKEN="<cloud-project-token>" \
   --show-report

Open your report at http://localhost:8080/, add detected problems to the baseline, and download the qodana.sarif.json file.
Upload the qodana.sarif.json file to your project root folder on GitHub.
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

If you want to update the baseline, you need to repeat these steps once again.

Starting from this, GitHub will generate alters only for the problems that were not added to the baseline as new.

To establish a quality gate additionally to a baseline, add this line to code_quality.yml right after the baseline-path line:

fail-threshold: <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.

Get a Qodana badge

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

Navigate to the workflow run that you previously configured.
On the workflow page, select Create status badge.
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: 10 December 2024