feat(bom): publish container image inventory as a doc artifact#763
Merged
Conversation
Refs #741, #739. First half of #741 — tooling + scheduled refresh. The user-facing prose ("explicit vs implicit", registry rationale, how to enumerate yourself) lands in a follow-up that wraps the auto-generated table. What this PR adds: - `pkg/bom.Metadata.Deterministic` flag suppressing per-run metadata (the `_Generated <timestamp> for ..._` line) in WriteMarkdown so the output is bit-for-bit reproducible across runs. Same Metadata is consumed by the planned per-bundle SBOM in pkg/bundler (#750), so this is a one-time API addition. - `tools/bom -deterministic` plumbs the flag through the CLI. - `make bom-docs` regenerates `docs/user/container-images.md` from the live registry, helm-rendering all chart references. - `make bom-check` regenerates and `git diff --exit-code`s the doc; fails on drift with a clear message pointing the contributor at `make bom-docs`. - `.github/workflows/bom-refresh.yaml` — scheduled weekly Monday refresh that opens (or updates) a chore PR when upstream chart rerenders cause drift in unpinned charts. Once #748/#749 finish, this should converge to a no-op; keeping the action enforces that property. - Doc registered in the VitePress sidebar under User Guide. Path-filtered PR-time `bom-check` gate (catching drift introduced by in-tree changes rather than upstream churn) is intentionally NOT wired into `make lint` or `merge-gate.yaml` in this PR. Deferred to a follow-up so this PR stays small. Until then, the scheduled refresh plus contributor discipline (`make bom-docs` after editing recipes) is the only enforcement. Initial doc snapshot: 22 components, 70 unique images across 11 registries. Image count drops from 71 to 70 because Docker Hub canonicalization (PR #747 review feedback) caught a duplicate.
mchmarny
added
enhancement
Contributor
|
🌿 Preview your docs: https://nvidia-preview-feat-bom-docs-automation.docs.buildwithfern.com/aicr |
This comment was marked as resolved.
This comment was marked as resolved.
Contributor
Coverage Report ✅
Coverage BadgeMerging this branch will increase overall coverage
Coverage by fileChanged files (no unit tests)
Please note that the "Total", "Covered", and "Missed" counts above refer to code statements instead of lines of code. The value in brackets refers to the test coverage of that file in the old version of the code. |
lockwobr
approved these changes
May 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
First half of #741 — publish the container image BOM as a committed doc artifact under
docs/user/container-images.mdwithmaketargets to regenerate / verify freshness, and a scheduled weekly refresh workflow. The user-facing prose (explicit vs implicit, registry rationale, how to enumerate yourself, link to the JSON release artifact) lands in a follow-up so this PR stays small.Motivation / Context
Today the BOM only exists as
dist/bom/bom.mdproduced ad-hoc bymake bom. To support customer security review and air-gap planning (#745) and the eventual provenance audit (#744), it needs to be a stable, addressable URL on the docs site. This PR makes it one.Refs #741, #739.
Type of Change
Component(s) Affected
pkg/bom—Deterministicflag onMetadata)tools/bom—-deterministic)Makefile—bom-docs,bom-check)docs/user/container-images.md, VitePress sidebar).github/workflows/bom-refresh.yaml)Implementation Notes
Determinism flag.
WriteMarkdownpreviously emitted_Generated <timestamp> for <name> <version>_on every run, which would force the committed doc to churn on every regeneration. AddedMetadata.Deterministic(off by default) that suppresses the line. Thetools/bom -deterministicflag plumbs it through. Future per-bundle SBOMs inpkg/bundler(#750) will consume the sameMetadata, so this is a one-time API addition.make bom-docs/make bom-check. New targets next to the existingmake bom:bom-docsregeneratesdocs/user/container-images.mdfrom the live registry (helm-renders all chart references; needs network).bom-checkregenerates andgit diff --exit-codes the file; fails on drift with a message pointing atmake bom-docs.Scheduled refresh.
.github/workflows/bom-refresh.yamlruns Mondays 06:00 UTC. Usespeter-evans/create-pull-request@v7.0.8(SHA-pinned, matches repo conventions) to open or updatechore/bom-refreshwhen the regenerated BOM differs from the committed copy. Catches upstream chart drift for components whose chart version isn't yet pinned (gated by #742; tracked under #749). Once every chart is pinned end-to-end, the action becomes a no-op — keeping it visible enforces that property.Sidebar. Doc registered under User Guide next to Component Catalog.
Out of scope (follow-up). Path-filtered PR-time
bom-checkgate. The repo'smerge-gate.yamluses a careful real-job/skip-job pair pattern withdorny/paths-filter; wiring the BOM check there belongs in a follow-up so this PR stays focused. Until then, scheduled refresh + contributor discipline (regenerate after editing recipes) is the only enforcement.Testing
Manual verification:
$ make bom-docs Regenerating docs/user/container-images.md (helm rendering, this can take ~30s)... bom: wrote /tmp/.../bom.cdx.json and /tmp/.../bom.md (22 components, 70 image refs) Wrote docs/user/container-images.md $ make bom-check docs/user/container-images.md is up to datepkg/bomcoverage held: 87.7% with newTestWriteMarkdown_DeterministicSuppressesGenerationLine.Initial inventory: 22 components, 70 unique images, 11 distinct registries. (Image count drops from 71 to 70 because the Docker Hub
library/canonicalization from #747 review caught a duplicate.)Risk Assessment
Deterministicis opt-in and defaults off (no behavior change for existing callers). New Make targets and a new scheduled workflow; no existing code paths modified. Easy to revert.Rollout notes: The committed
docs/user/container-images.mdbecomes the canonical reference for the deployed image set. The scheduled refresh starts firing the Monday after merge.Checklist
make testwith-race)make lint)git commit -S)