Configuring Qodana Custom Inspections and HTML Reports in GitHub Actions

To get fine‑grained control of which inspections Qodana runs and to publish an interactive HTML report to the Qodana dashboard from a GitHub Actions workflow, add a .qodana.yml file that tweaks inspections and a workflow that runs the official Qodana action with a token and a report directory.

Worked configuration

.qodana.yml (repository root)

# .qodana.yml
inspections:
  # Disable a specific inspection that is noisy for this project
  java:S1192: disabled
  # Treat another inspection as an error instead of its default warning
  java:S106: error

report:
  type: html
  output: ./qodana-report

This file lives at the root of the repository. The inspections section lets you enable, disable, or change the severity of any inspection supported by the chosen Qodana image. The report section tells Qodana to generate a static HTML dashboard in the ./qodana-report directory after the analysis finishes.

GitHub Actions workflow (`.github/workflows/qodana.yml`)

name: Qodana analysis

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  qodana:
    runs-on: ubuntu-latest
    permissions:
      contents: read  # needed to checkout the code
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Run Qodana and upload report
        uses: qodana/qodana-action@v1
        with:
          token: ${{ secrets.QODANA_TOKEN }}
          config-file: .qodana.yml
          report-dir: ./qodana-report

      - name: Upload HTML report as artifact
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: qodana-html-report
          path: ./qodana-report

The workflow checks out the code, runs the qodana/qodana-action which pulls the official Docker image (e.g., ghcr.io/jetbrains/qodana-jvm:2026.2), applies the .qodana.yml configuration, and writes the HTML report to ./qodana-report. The final step uploads that directory as a workflow artifact, and the action also pushes the report to the Qodana dashboard when a valid QODANA_TOKEN secret is present.

Limits and common mistakes

• Image tag mismatch – Using an outdated tag like 2025.1 may miss newer inspections or bug fixes. Verify the tag matches the Qodana version you intend to use; check the GitHub Container Registry for the latest.
• YAML syntax errors – Missing colons, incorrect indentation, or using tabs instead of spaces cause Qodana to fail silently. Validate the file with a YAML linter before committing.
• Invalid or scoped token – The QODANA_TOKEN secret must be a JetBrains account token with the qodana:write scope. An invalid token results in a failed upload step; check the action logs for "Unauthorized" messages.
• Report directory mismatch – If the output path in .qodana.yml does not equal the report-dir input of the action (or the artifact upload path), the HTML dashboard will not be captured. Keep them identical, e.g., both ./qodana-report.
• Over‑disabling inspections – Disabling inspections hides potential problems. Prefer lowering severity to warning or info instead of disabled unless the inspection is truly irrelevant.

To verify locally, run:

docker run --rm -v "$(pwd)":/project ghcr.io/jetbrains/qodana-jvm:2026.2 -c .qodana.yml

This command mounts the current directory into the container, applies the .qodana.yml configuration, and writes ./qodana-report. Open qodana-report/index.html in a browser to confirm that the expected inspections appear (e.g., java:S1192 missing, java:S106 shown as an error).