Shipping an SBOM alongside each release gives your customers and auditors a precise record of what is inside a given version. This guide explains how to produce the SBOM and attach it to a release, and why the timing of the export matters. It is written for release engineers and maintainers.
Why attach the SBOM to the release
A release is the unit your customers actually consume. By attaching the SBOM to the tagged release, anyone can later answer "what components are in version X?" without rebuilding anything. This is exactly the question that comes up during a supply-chain incident or a security review.
Step 1 — Export at release time
Generate the SBOM from the exact tree you are releasing — typically right after checkout of the tag and after dependencies are resolved:
vg sbom export --format cyclonedx --out sbom.cdx.json
Naming the file with the version makes it self-describing in a release's asset list, for example sbom-1.4.0.cdx.json:
vg sbom export --format cyclonedx --out sbom-1.4.0.cdx.json
Step 2 — Publish it as a release asset
Upload the file to your release. On GitHub, this means attaching it to the GitHub Release for the tag; on GitLab, attach it to the release or link it from the release notes. The file is a normal artifact, so any release tooling can carry it.
Step 3 — Reference it in release notes
A short line in the release notes — "A CycloneDX SBOM is attached as sbom-1.4.0.cdx.json" — helps consumers find it without digging.
Producing more than one format
If different consumers expect different formats, export each one. For example, CycloneDX for tooling and SPDX for a procurement process:
vg sbom export --format cyclonedx --out sbom-1.4.0.cdx.json
vg sbom export --format spdx --out sbom-1.4.0.spdx.json
Tips
- Export from the release tag, not from an in-progress branch, so the inventory matches what ships.
- Keep the SBOM with the release permanently; it is the historical record for that version.
- If you push scans to Vibgrate Cloud, the dashboard gives you a complementary, searchable view across releases.
Troubleshooting
- SBOM does not match the build? Confirm dependencies were installed before export and that you exported from the tagged commit.
- Consumers cannot parse it? Verify they expect the format you exported; see "SBOM Formats Supported by Vibgrate CLI".
Related
- "Generate an SBOM in Your CI Pipeline" to automate this at release time.
- "SBOM for Compliance and Audit Evidence" explains retention and audit use.
- See the vg sbom command documentation for all export options.