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:
| Code | Meaning |
|---|---|
0 | The command completed and every evaluated gate passed. |
1 | The command completed, but an evaluated health or quality gate failed (quality-gate, check-architecture, doctor, maintain-database). |
2 | The command could not run: usage, configuration, validation, runtime, or infrastructure error. |
3 | The 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:
jq '.data.sarif' artifacts/quality-gate.json > artifacts/knossos.sarifGitHub 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:
jq -r '.data.release_notes.markdown' artifacts/trends.json \
> artifacts/architecture-change.mdReviewed 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.jsonif 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.