Skip to content

Commit 1a29fe3

Browse files
stacknilstacknil
authored
[codex] Add GitHub Actions consumer example
Add docs-only GitHub Actions consumer example for running sbom-diff-risk from a GitHub Release wheel and uploading generated outputs. No workflows, runtime behavior, package metadata, schema, examples, release tags, or publishing status changes.
1 parent 3cd2236 commit 1a29fe3

2 files changed

Lines changed: 139 additions & 0 deletions

File tree

‎tools/sbom-diff-and-risk/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ It uses conservative heuristics for change intelligence. By default it does not
1111
This project has two different provenance stories:
1212

1313
For a concise reviewer-facing overview, start with [docs/reviewer-brief.md](docs/reviewer-brief.md). For reproducible review evidence and verification commands, use [docs/reviewer-evidence-pack.md](docs/reviewer-evidence-pack.md). For machine-readable JSON output shape, see [docs/report-schema.md](docs/report-schema.md). For CI consumption of summary-only output, see [docs/summary-json-ci-cookbook.md](docs/summary-json-ci-cookbook.md).
14+
For a consumer-facing GitHub Actions example, see [docs/github-actions-consumer-example.md](docs/github-actions-consumer-example.md).
1415

1516
1. If you want to verify `sbom-diff-and-risk` itself, start with [docs/verification.md](docs/verification.md).
1617
2. If you want to use `sbom-diff-and-risk` to analyze third-party dependency provenance, start with [Dependency provenance analysis](#dependency-provenance-analysis-opt-in) and [Dependency provenance reporting](#dependency-provenance-reporting).

‎tools/sbom-diff-and-risk/docs/github-actions-consumer-example.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# GitHub Actions consumer example
2+
3+
This page shows how another repository could run `sbom-diff-risk` from GitHub
4+
Actions and upload the generated review artifacts.
5+
6+
It is documentation only. It is not a workflow for this repository, and it does
7+
not change the `sbom-diff-risk` CLI or publishing model.
8+
9+
Production PyPI publishing is intentionally deferred, so consumers should not
10+
install `sbom-diff-and-risk` from production PyPI. Use a GitHub Release asset or
11+
a local checkout instead.
12+
13+
## Example workflow
14+
15+
This example downloads the released wheel from the public GitHub Release, runs a
16+
local comparison, writes JSON, Markdown, summary JSON, and SARIF outputs, applies
17+
an explicit local threshold to `summary.json`, and uploads the outputs as CI
18+
artifacts.
19+
20+
Replace the placeholder input paths with files from the consumer repository.
21+
22+
```yaml
23+
name: Dependency diff review
24+
25+
on:
26+
pull_request:
27+
workflow_dispatch:
28+
29+
permissions:
30+
contents: read
31+
32+
jobs:
33+
dependency-diff:
34+
runs-on: ubuntu-latest
35+
36+
steps:
37+
- name: Check out consumer repository
38+
uses: actions/checkout@v6
39+
40+
- name: Set up Python
41+
uses: actions/setup-python@v6
42+
with:
43+
python-version: "3.x"
44+
45+
- name: Download sbom-diff-and-risk release wheel
46+
env:
47+
GH_TOKEN: ${{ github.token }}
48+
run: |
49+
mkdir -p .tooling/sbom-diff-risk
50+
gh release download v0.6.0 \
51+
--repo stacknil/scientific-computing-toolkit \
52+
--pattern "sbom_diff_and_risk-0.6.0-py3-none-any.whl" \
53+
--dir .tooling/sbom-diff-risk
54+
55+
- name: Install sbom-diff-risk
56+
run: |
57+
python -m pip install .tooling/sbom-diff-risk/sbom_diff_and_risk-0.6.0-py3-none-any.whl
58+
59+
- name: Compare dependency evidence
60+
run: |
61+
mkdir -p outputs
62+
sbom-diff-risk compare \
63+
--before path/to/before-sbom.json \
64+
--after path/to/after-sbom.json \
65+
--format auto \
66+
--out-json outputs/report.json \
67+
--out-md outputs/report.md \
68+
--summary-json outputs/summary.json \
69+
--out-sarif outputs/report.sarif
70+
71+
- name: Apply local summary threshold
72+
run: |
73+
python - <<'PY'
74+
import json
75+
from pathlib import Path
76+
77+
summary = json.loads(Path("outputs/summary.json").read_text(encoding="utf-8"))
78+
risk_counts = summary["risk_counts"]
79+
80+
max_new_packages = 2
81+
new_package_count = risk_counts.get("new_package", 0)
82+
print(f"new_package={new_package_count}")
83+
84+
if new_package_count > max_new_packages:
85+
raise SystemExit(
86+
f"new_package count exceeds local threshold: {max_new_packages}"
87+
)
88+
PY
89+
90+
- name: Upload dependency diff outputs
91+
uses: actions/upload-artifact@v7
92+
with:
93+
name: dependency-diff-outputs
94+
path: |
95+
outputs/report.json
96+
outputs/report.md
97+
outputs/summary.json
98+
outputs/report.sarif
99+
```
100+
101+
## Local checkout variant
102+
103+
If the consumer repository vendors or checks out this toolkit repository, install
104+
from that local checkout instead of downloading a release wheel:
105+
106+
```yaml
107+
- name: Install sbom-diff-risk from local checkout
108+
run: |
109+
python -m pip install path/to/scientific-computing-toolkit/tools/sbom-diff-and-risk
110+
```
111+
112+
## What the example proves
113+
114+
- The consumer workflow runs deterministic local diff analysis over files the
115+
consumer repository provides.
116+
- `outputs/report.json` contains the full machine-readable report.
117+
- `outputs/report.md` contains the human-readable review report.
118+
- `outputs/summary.json` contains the same object as `report.json["summary"]`.
119+
- `outputs/report.sarif` can be uploaded or inspected by consumers that want
120+
SARIF output.
121+
- The threshold step is a local consumer policy choice, not a built-in security
122+
verdict.
123+
124+
## Boundaries
125+
126+
- The example does not use production PyPI.
127+
- Production PyPI publishing remains intentionally deferred.
128+
- The example does not require secrets.
129+
- Default `sbom-diff-risk` runs do not perform hidden network access.
130+
- Downloading the GitHub Release wheel is explicit network access by the
131+
workflow.
132+
- `sbom-diff-risk` is not a CVE scanner.
133+
- The output is not a dependency safety oracle.
134+
- Replace all placeholder input paths with non-private paths from the consumer
135+
repository.
136+
137+
For compact summary consumption patterns, see
138+
[summary-json-ci-cookbook.md](summary-json-ci-cookbook.md).

0 commit comments

Comments
 (0)