isabella232 / qodana-action

⚙️ Scan your Java, Kotlin, PHP, Python, JavaScript, TypeScript projects at GitHub with Qodana

Qodana Scan

Qodana is a code quality monitoring tool that identifies and suggests fixes for bugs, security vulnerabilities, duplications, and imperfections. Using this GitHub Action, run Qodana with your GitHub workflow to scan your Java, Kotlin, PHP, Python, JavaScript, TypeScript projects ( and other supported technologies by Qodana).

Table of Contents

• Qodana Scan
  • Usage
  • Configuration
  • Issue Tracker
  • License

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:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: 'Qodana Scan'
        uses: JetBrains/[email protected]
        with:
          linter: jetbrains/qodana-<linter>

Using this workflow, Qodana will run on the main branch, release branches, and on the pull requests coming to your repository. Inspection results will be available in the GitHub UI. The jetbrains/qodana-<linter> option specifies a Qodana linter.

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@v1
        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.

💡 GitHub code scanning does not export inspection results to third-party tools, which means that you cannot use this data for further processing by Qodana. In this case, you have to set up baseline and quality gate processing on the Qodana side prior to submitting inspection results to GitHub code scanning, see the Quality gate and baseline section for details.

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.

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.

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:

1. Run Qodana locally over your project:

docker run --rm -v <source-directory>/:/data/project/ \
  -p 8080:8080 jetbrains/qodana-<linter> --show-report

2. Open your report at http://localhost:8080/, add detected problems to the baseline, and download the qodana.sarif.json file.

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

4. Append this line to the Qodana Scan action configuration in the code_quality.yml file:

baseline-path: 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 the 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.

GitHub Pages

If you wish to study Qodana reports directly on GitHub, you can host them on your GitHub Pages repository using this example workflow:

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ${{ runner.temp }}/qodana/results/report
          destination_dir: ./

Hosting of multiple Qodana reports in a single GitHub Pages repository is not supported.

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.

Configuration

Name	Description	Default Value
linter	Official Qodana Docker image. Required.	jetbrains/qodana-jvm-community:latest
project-dir	The project's root directory to be analyzed. Optional	${{ github.workspace }}
results-dir	Directory to store the analysis results. Optional.	${{ runner.temp }}/qodana/results
cache-dir	Directory to store Qodana caches. Optional.	${{ runner.temp }}/qodana/caches
idea-config-dir	IntelliJ IDEA configuration directory. Optional.	-
gradle-settings-path	Provide path to gradle.properties file. An example: "/your/custom/path/gradle.properties". Optional.	-
additional-volumes	Mount additional volumes to Docker container. Multiline input variable: specify multiple values with newlines. Optional.	-
additional-env-variables	Pass additional environment variables to docker container. Multiline input variable: specify multiple values with newlines. Optional.	-
fail-threshold	Set the number of problems that will serve as a quality gate. If this number is reached, the pipeline run is terminated. Optional.	-
inspected-dir	Directory to be inspected. If not specified, the whole project is inspected by default. Optional.	-
baseline-path	Run in baseline mode. Provide the path to an existing SARIF report to be used in the baseline state calculation. Optional.	-
baseline-include-absent	Include the results from the baseline absent in the current Qodana run in the output report. Optional.	false
changes	Inspect uncommitted changes and report new problems. Optional.	false
script	Override the default docker scenario. Optional.	-
profile-name	Name of a profile defined in the project. Optional.	-
profile-path	Absolute path to the profile file. Optional.	-
token	Qodana Cloud token, if specified, the report will be sent to Qodana Cloud. Optional.	-
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
use-caches	Utilize GitHub caches for Qodana runs. Optional.	true
additional-cache-hash	Allows customizing the generated cache hash. Optional.	${{ github.sha }}
use-annotations	Use annotation to mark the results in the GitHub user interface. Optional.	true
github-token	GitHub token to be used for uploading results. Optional.	${{ github.token }}

Issue Tracker

All the issues, feature requests, and support related to the Qodana GitHub Action are handled on YouTrack.

If you'd like to file a new issue, please use the link YouTrack | New Issue.

License

The GitHub Action repository

This repository contains source code for Qodana GitHub Action and is licensed under Apache-2.0.

Qodana Docker images

Qodana Community images

View license information for the Qodana Community images.

Qodana Docker images may contain other software which is subject to other licenses, for example, Bash relating to the base distribution or with any direct or indirect dependencies of the primary software.

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

Qodana EAP images

Using the Qodana EAP Docker images, you agree to JetBrains EAP user agreement and JetBrains privacy policy. The docker image includes an evaluation license which will expire in 30-day. Please ensure you pull a new image on time.