Qodana Baseline: filter legacy noise and gate only new issues in CI

When a team inherits a legacy codebase, Qodana often surfaces thousands of pre‑existing code quality violations. These issues drown out new ones, making it hard to enforce quality gates on fresh code and leaving CI pipelines either failing on every commit or being disabled entirely. Useful takeaway: Qodana’s Baseline feature lets you snapshot the current issue state, commit that snapshot, and configure future runs to report only newly introduced problems.

How Qodana Baseline diffs new issues

Qodana runs a set of inspections defined by a profile against your code and produces a report of problems. Without a baseline, every run reports the full set, so the count stays high and new violations blend in. With a baseline, Qodana compares the current inspection results against the snapshot and surfaces only the diff—issues that are new, removed, or modified. This lets your CI gate fail only when new problems appear, not when the project inherits historical debt.

Inspection profile and version anchoring

The baseline is tied to the inspection profile and the Qodana version that generated it. If you upgrade Qodana or adjust the profile, the issue identifiers and rules may change, making the old baseline less accurate. Regenerating the baseline after such changes keeps the diff meaningful.

problemId: string; file: string; line: number

Generating and committing a baseline

Run the baseline command on a clean checkout of the repository. The command snapshots the current inspection results into a JSON file that you commit to version control.

Local example

qodana --baseline --output baseline.json

Where to run: any machine with Qodana installed and access to the project source. Required permissions: read access to the source tree; no write access beyond the project directory is needed. Meaningful placeholders: replace baseline.json with your preferred path if desired. Expected checks: after the command finishes, inspect the generated file for entries matching the current issue count. Relevant risks: the file is specific to the Qodana version and inspection profile in use; upgrading either may require regenerating the baseline to avoid false diffs.

Integrating baseline in GitHub Actions

In a CI workflow, you can use the baseline to gate only on new issues. The general pattern is: download the baseline artifact, run Qodana with the baseline flag, and configure the fail threshold to trigger only when new problems appear.

Two-job workflow pattern

1. First job: generates the baseline and uploads it as an artifact.

   steps:
     - name: Install Qodana
       run: |
         # installation steps vary by platform
         curl -L https://download.jetbrains.com/qodana/qodana-latest.tar.gz | tar -xz -C /opt
         export PATH=\"/opt/qodana/bin:$PATH\"
     - name: Generate baseline
       run: qodana --baseline --output baseline.json
     - name: Upload baseline artifact
       uses: actions/upload-artifact@v4
       with:
         name: qodana-baseline
         path: baseline.json

2. Second job: downloads the baseline and runs Qodana against it, failing only on new issues.

   steps:
     - name: Download baseline artifact
       uses: actions/download-artifact@v4
       with:
         name: qodana-baseline
         path: .
     - name: Run Qodana with baseline
       run: qodana --baseline baseline.json --fail-threshold NEW_ISSUES>0

Where to run: GitHub Actions jobs. Required permissions: the workflow needs contents: read to download the artifact and contents: write if the baseline path is in the repository; otherwise read-only suffices. Meaningful placeholders: baseline.json path, NEW_ISSUES>0 threshold. Expected checks: on a branch with no code changes, the workflow should pass, confirming that only pre-existing issues are ignored. Relevant risks: if the baseline file drifts from the current profile or Qodana version, the diff may produce false positives or miss new issues. Large baseline files can also increase workflow runtime and artifact storage costs.

Trade-offs and how to verify

• Version and profile coupling: Baseline files embed the inspection profile and Qodana version. A version bump or profile tweak often necessitates regenerating the baseline.

• File size: In large repositories, the baseline JSON can reach several megabytes. Storing it as a CI artifact adds transfer overhead and repository size.

• Branch synchronization: The baseline reflects the state of the branch at generation time. If the baseline lives on a long‑lived branch, merging it into other branches may require an updated snapshot.

Practical verification: Run the workflow on a branch with no code changes; the fail‑threshold NEW_ISSUES>0 condition should pass, confirming that only pre-existing issues are suppressed. Introduce a deliberate new violation (for example, add a new code inspection breach) and re‑run the workflow; it should fail, demonstrating that the baseline correctly isolates newly introduced problems. Compare baseline entry counts to a fresh Qodana run without the baseline flag to ensure the snapshot captures the expected issue volume.

Actionable next step

Start by running qodana --baseline --output baseline.json on a local clone of your repository. Inspect the generated file to confirm it contains the expected issue entries, commit it to your default branch, and add a CI job that references the baseline with a NEW_ISSUES>0 threshold. From there, new code quality problems will surface clearly, and your team can focus fixes on what actually matters.