Qodana is a code quality monitoring tool that identifies and suggests fixes for bugs, security vulnerabilities, duplications, and imperfections.
Table of Contents
- Qodana Scan
- Issue Tracker
The Qodana Scan GitHub action allows you to run Qodana on a GitHub repository.
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
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/[email protected]
env:
QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }} # read the steps about it below
To set QODANA_TOKEN
environment variable in the build configuration:
- In the GitHub UI,
create the
QODANA_TOKEN
encrypted secret and save the project token as its value. - In the GitHub workflow file,
add
QODANA_TOKEN
variable to theenv
section of theQodana Scan
step:
Using this workflow, Qodana will run on the main branch, release branches, and on the pull requests coming to your repository.
Note: fetch-depth: 0
is required for checkout in case Qodana works in pull request mode
(reports issues that appeared only in that pull request).
We recommend that you have a separate workflow file for Qodana because different jobs run in parallel
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 theqodana.yaml
file in your repository root - Or set the action
args
property with the quick-fix strategy to use:--apply-fixes
or--cleanup
- Specify
- Set
push-fixes
property topull-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, setpr-mode
tofalse
: 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 forpush-fixes
property: allow GitHub Actions to create and approve pull requests
- If you use
Example configuration:
- name: Qodana Scan
uses: JetBrains/[email protected]
with:
pr-mode: false
args: --apply-fixes
push-fixes: pull-request
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Note Qodana could automatically modify not only the code, but also the configuration in
.idea
: if you do not wish to push these changes, add.idea
to your.gitignore
file.
If you want to do different git
operations in the same job, you can disable push-fixes
and do the wanted operations manually
💡Full script example
name: Qodana
on:
workflow_dispatch:
pull_request:
push:
branches:
- master
- 'releases/*'
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 }}
fetch-depth: 0
- name: 'Qodana Scan'
uses: JetBrains/[email protected]
with:
args: --cleanup
- run: |
git config user.name github-actions
git config user.email [email protected]
git checkout -b quick-fixes-$GITHUB_RUN_ID
git add -- . ':!.idea'
git commit -m "I fixed some issues"
git push origin quick-fixes-$GITHUB_RUN_ID
gh pr create --repo $GITHUB_REPOSITORY --base $GITHUB_REF_NAME --head quick-fixes-$GITHUB_RUN_ID --title "Pull requests" --body "I fixed some issues"
env:
GH_TOKEN: ${{ github.token }}
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.
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.
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:
- 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 themain
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.
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 --show-report
-
Open your report at
https://localhost:8080/
, add detected problems to the baseline, and download theqodana.sarif.json
file. -
Upload the
qodana.sarif.json
file to your project root folder on GitHub. -
Append
--baseline,qodana.sarif.json
argument to the Qodana Scan action configurationargs
parameter in thecode_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 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.
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.
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.1-${{ github.ref }}-${{ github.sha }} |
additional-cache-key |
Set the additional cache key. Optional. | qodana-2024.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 |
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 |
All the issues, feature requests, and support related to Qodana are handled on YouTrack.
If you'd like to file a new issue, please use the link YouTrack | New Issue.