Integrating JetBrains Qodana into CI: Docker, Thresholds, and SARIF Fail‑Builds

Desired Outcome

Automate static analysis of a Java/Kotlin repository in a CI pipeline, enforce a minimum quality gate, and surface detailed SARIF reports for downstream tooling.

Prerequisites

• Docker 20.10+ installed on the CI runner.
• Valid QODANA_TOKEN from JetBrains Qodana Cloud; store it as a secret in the CI system.
• Repository root contains a .qodana.yml configuration file.
• CI job has outbound network access to https://qodana.jetbrains.com for license validation.

Configuration – .qodana.yml

The file defines language‑specific rules, severity thresholds, and output format. Example for a JVM project:

language: java
output:
  format: sarif
  path: report.sarif
thresholds:
  critical: 0
  major: 5
  minor: 10
  info: 20
rules:
  - id: "java:S106"
    severity: "warning"
    enabled: true
  - id: "java:S1193"
    severity: "critical"
    enabled: true

Setting critical: 0 forces the build to fail if any critical issue is found. Adjust the numbers to match your team's quality gate.

Docker‑Based Analysis

Command Line Test

Run the container locally to confirm the setup before adding it to CI:

docker run --rm \
  -v $(pwd):/project \
  -w /project \
  -e QODANA_TOKEN=YOUR_TOKEN \
  jetbrains/qodana-jvm:latest \
  --report \
  --report-html /project/report.html

After execution, report.sarif and report.html will appear in the repository root. Verify that report.sarif contains entries and that the container exits with status 0.

GitHub Actions Example

Below is a minimal job that mounts the repository, runs Qodana, and fails on any critical findings.

name: Qodana Static Analysis
on: [push, pull_request]
jobs:
  qodana:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Qodana
        uses: docker://jetbrains/qodana-jvm:latest
        with:
          args: "--report"
        env:
          QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}
        working-directory: .
      - name: Parse SARIF and fail on critical
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: report.sarif
          fail_on_error: true
          # The action automatically fails if any issue has level 'error' or higher.

Because the SARIF file marks critical issues as error, the upload step will exit non‑zero and stop the job.

Expected Checks

1. Container Exit Code – Should be 0 unless authentication fails.
2. SARIF Presence – report.sarif must exist in the working directory.
3. Critical Issue Count – Parse the SARIF file; if any ruleId with level="error" is present, the job should fail.
4. HTML Report – Optional; verify report.html exists for manual review.

Recovery & Troubleshooting

• Authentication Error – Verify QODANA_TOKEN is correct and not expired. Store it in CI secrets with read‑only access.
• No SARIF Generated – Check that the container was run with --report and that the working directory is set to the repository root.
• Memory‑Intensive Analysis – For large codebases, increase the Docker runner’s memory limit or split the analysis into modules.
• False Positives – Add suppression rules to .qodana.yml or use --skip-issues to ignore specific rule IDs.

Limitations

• The example uses jetbrains/qodana-jvm:latest; pinning to a specific tag (e.g., jetbrains/qodana-jvm:2024.1.0) can avoid unexpected breaking changes.
• Network access is mandatory for license validation; offline CI environments require pre‑cached images and a local license server.
• Large repositories may exceed the default container memory; monitor docker stats during runs.

Next Steps

Once the CI job is stable, consider adding a complementary step that archives the HTML report in an artifact or uploads it to a static site for long‑term visibility. You can also use the Qodana CLI to generate a JSON summary for integration with issue trackers.