Qodana Architecture: Container Isolation, SARIF, and Failure‑Safe Design

Qodana is a container‑based static‑analysis engine that bundles JetBrains IDE inspections. It runs inside a Docker image and mounts your source tree so the same logic a developer sees in the IDE is executed on the CI runner.

Requirements for a Reliable Qodana Pipeline

• Docker runtime – The CI agent must support Docker (or a compatible container runtime) to pull the Qodana image.
• Dependency access – The image needs to resolve project dependencies (Maven, Gradle, npm, etc.). Without a reachable repository or a pre‑filled cache, the analysis falls back to syntax checks.
• Machine‑readable output – Qodana exports results in SARIF. The pipeline should capture this file for downstream quality gates.

The Minimal, Ephemeral Design

The simplest architecture is a one‑off container that mounts the source tree read‑only and writes its own cache to a separate volume. This keeps the host untouched and avoids stale state between runs.

Example: GitHub Actions for a Java Project

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run Qodana
        uses: jetbrains/qodana-action@v2
        with:
          image: jetbrains/qodana-java:latest
          project-path: .
          output-path: qodana-results.sarif
          cache-dir: /tmp/qodana-cache

In this snippet the cache-dir is a separate volume that persists only between workflow runs, preventing the container from writing into the checked‑out source.

Data Boundaries and Trust Zones

• Read‑only mount – Mount the repository as ro if the runtime supports it. Qodana only needs to read the files.
• Dedicated cache volume – The engine writes indexes and dependency caches to a writable volume that is isolated from the source.

Operational Checks

1. Memory limits – Allocate at least 4 GB of RAM for large monorepos. Monitor with docker stats <container> and set --memory=4g on docker run or the CI runner config.
2. Dependency resolution – Verify that the log contains "Resolving dependencies" and no network errors. If the image cannot reach Maven Central, pre‑populate a local cache or enable offline mode.
3. Result parity – Run qodana run --project-path=. --out-dir=local locally, then compare the SARIF JSON with the CI output using diff local/sarif.json qodana-results.sarif. Differences indicate version drift.

Failure Modes

• Out‑of‑Memory (OOM) – Large codebases can exhaust the container’s memory. The container will be killed by the kernel, leaving no SARIF file.
• Timeouts – If dependency resolution stalls, the analysis may exceed the CI job timeout and abort.
• Cache corruption – Re‑using an old cache volume can cause stale indexes, leading to false positives.

When to Change the Design

• Monorepo with multiple languages – Use language‑specific Qodana images or a multi‑step pipeline to avoid pulling unnecessary tooling.
• Offline CI environment – Build a custom image that bundles all required dependencies and caches.
• Resource‑constrained runners – Split the analysis into smaller chunks or use a dedicated high‑memory runner.

Verification Checklist

• Confirm the source tree is unchanged after the run by running git diff --stat inside the container.
• Set the Docker memory limit to 2 GB and observe at which point the analysis fails; use this to tune the production limit.
• Generate a SARIF file locally and on CI, then compare the runs[0].results count to ensure parity.

By following this architecture note you guarantee that Qodana’s inspection logic is identical across developers and CI, while keeping the host environment clean and predictable.