Skip to content

CI and editor integration ​

Knossos uses the same pinned Docker runtime for local, editor, and CI scans. The source tree is mounted read-only, derived graph state is stored separately, and scans run with networking disabled.

Stable exit codes ​

CLI commands use the following automation contract:

CodeMeaning
0The command completed and every evaluated gate passed.
1The command completed, but an evaluated health or quality gate failed (quality-gate, check-architecture, doctor, maintain-database).
2The command could not run: usage, configuration, validation, runtime, or infrastructure error.
3The command completed, but its list is incomplete: a bound or time limit cut it (dead-code, diagnostics). The output says truncated: true.

Do not treat code 2 as a quality finding. It means the result could not be evaluated reliably and the job should fail visibly.

Treat code 3 as "rerun with a larger budget", not as a finding or an error. Everything listed is true, but the list stops short; raise --candidate-timeout for dead-code, or narrow diagnostics with --severity or --path. Before this code existed an incomplete list exited 2, so a script that only tests for a non-zero status still fails the job, while one that compares with 2 needs to handle 3 as well.

Machine-readable reports ​

Run quality-gate with --sarif --json. Its JSON envelope contains SARIF 2.1.0 at .data.sarif; extract it without changing the original command status:

sh
jq '.data.sarif' artifacts/quality-gate.json > artifacts/knossos.sarif

GitHub can upload this file with github/codeql-action/upload-sarif. GitLab should retain it as an ordinary job artifact unless a separately configured integration explicitly accepts SARIF; GitLab's SAST report schema is different.

architecture-trends --release-from=SNAPSHOT --json places deterministic Markdown at .data.release_notes.markdown:

sh
jq -r '.data.release_notes.markdown' artifacts/trends.json \
  > artifacts/architecture-change.md

Reviewed baseline workflow ​

Quality budgets compare the active graph with a complete retained snapshot. Persist /data between jobs and set KNOSSOS_BASELINE_SNAPSHOT to a snapshot that was reviewed on the default branch. Never silently replace that variable when a pull request fails; baseline adoption is an explicit repository or CI configuration change.

The examples expect a checked-in knossos-budgets.json. Add --policies=/workspace/architecture-policies.json when the repository also has a checked-in policy file. See architecture quality budgets for both formats.

One call for a pull request review ​

For budget deltas and blast radius on a pull request, review_diff composes changed_files_impact, check_architecture, quality_gate, and dependency_cycles into a single result scoped to the changed components, so a CI review step or PR comment job makes one call instead of chaining four. It takes the same baseline and policy inputs. See review diff.

Ready-to-adapt recipes ​

  • GitHub Actions restores retained graph state, scans, preserves the gate exit code, uploads SARIF and Markdown, and saves history only on the default branch.
  • GitLab CI applies the same container, mounts, baseline, reports, and quality gate.
  • VS Code tasks runs the repository's pinned quality container and a read-only local scan. Copy it to .vscode/tasks.json if desired.

Pin third-party CI actions and images to immutable digests according to the repository's supply-chain policy before production use. Limit write access to the retained data cache, keep source read-only, and do not expose untrusted forks to cache-save credentials.