Skip to content

[codex] Reflow summary-json CI cookbook Markdown #34

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stacknil merged 1 commit into from
May 2, 2026
Merged

[codex] Reflow summary-json CI cookbook Markdown #34

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 14 additions & 6 deletions tools/sbom-diff-and-risk/docs/summary-json-ci-cookbook.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,12 @@
# Summary JSON CI cookbook

This page shows how to consume `--summary-json PATH` in CI without changing the `sbom-diff-risk` analysis model.
This page shows how to consume `--summary-json PATH` in CI without changing
the `sbom-diff-risk` analysis model.

`--summary-json` writes a compact machine-readable JSON object. It is the same object as `report.json["summary"]`, and is useful for CI dashboards, job summaries, and small local gates where a repository wants to set its own thresholds.
`--summary-json` writes a compact machine-readable JSON object. It is the same
object as `report.json["summary"]`, and is useful for CI dashboards, job
summaries, and small local gates where a repository wants to set its own
thresholds.

## Minimal command

Expand All @@ -14,11 +18,13 @@ sbom-diff-risk compare \
--summary-json outputs/summary.json
```

The full report remains available at `outputs/report.json`. The compact summary-only object is written to `outputs/summary.json`.
The full report remains available at `outputs/report.json`. The compact
summary-only object is written to `outputs/summary.json`.

## Python consumer

This example reads the summary and applies an explicit local threshold. The threshold is chosen by the caller; it is not a built-in package safety verdict.
This example reads the summary and applies an explicit local threshold. The
threshold is chosen by the caller; it is not a built-in package safety verdict.

```python
import json
Expand All @@ -41,7 +47,8 @@ if risk_counts.get("new_package", 0) > max_new_packages:

## PowerShell consumer

This example uses `ConvertFrom-Json` and applies the same kind of explicit local threshold.
This example uses `ConvertFrom-Json` and applies the same kind of explicit
local threshold.

```powershell
$summary = Get-Content outputs/summary.json -Raw | ConvertFrom-Json
Expand All @@ -65,7 +72,8 @@ if ($newPackageCount -gt $maxNewPackages) {
- `summary.policy` appears only when policy evaluation is applied.
- `summary.enrichment` appears only when PyPI or Scorecard enrichment is used.
- `unchanged` is absent because unchanged components are not modeled.
- Absence of `summary.policy` or `summary.enrichment` means the feature was not used, not that it failed.
- Absence of `summary.policy` or `summary.enrichment` means the feature was
not used, not that it failed.
- Consumers should treat new unrecognized fields as additive data.

## Non-claims
Expand Down