You attach an SBOM or signature by pushing it as its own manifest in the same repository with a subject field that names the image digest. Registries that support the OCI Referrers API then list it for that image. Older registries use a fallback tag derived from the digest.
The idea in plain terms
An image is identified by a digest. A signature, SBOM or attestation is another artifact that refers to that digest. The OCI distribution specification, version 1.1, defines how: the extra artifact is a manifest whose subject field points at the target manifest. Its artifactType says what it is, such as an SBOM or a signature.
A client then asks the registry for the referrers of that digest, using the referrers endpoint under the repository name. The response is an image index listing the manifests whose subject matches that digest, and it can be filtered by artifact type. The registry returns an empty list if there are none.
Two ways clients find them
| Method | How it works | Caveat |
|---|---|---|
| Referrers API | Registry answers the referrers request | Registry must support OCI 1.1 |
| Referrers tag schema | Client reads an index at a tag built from the digest, such as sha256 then a hyphen then the hash | Clients maintain the tag, so concurrent updates can race and lose entries |
The specification notes that a registry must accept a manifest whose subject does not exist yet, so you can push the image and the artifact in either order.
Steps
- Build the image and push it. Record the digest.
- Generate the SBOM from the final image by digest.
- Push the SBOM as an artifact with the image as its subject, and set its artifact type.
- Sign the image, and push the signature the same way.
- List referrers for the digest to confirm both attached.
- Have deploy tooling verify the signature and read the SBOM before allowing the image.
What attaching does and does not give you
It keeps the metadata next to the image, so consumers do not need a separate portal. It does not prove the SBOM is accurate or the image is safe. A signature shows who published and that the content is unchanged; see what a signature proves.
Check support first. Some registries or mirrors drop artifacts they do not recognize when copying an image, and a copy can change the digest. Test a full promotion path from build registry to production registry and confirm the referrers survive.
Quick check
Does the SBOM change the image digest?
No. It is a separate manifest that points to the image. The image digest stays the same.
What if my registry lacks the Referrers API?
Clients can use the fallback tag scheme, with the race caveat, or you can store SBOMs in a separate system keyed by digest.
Safeguard builds and scans SBOMs; you can start with the free scan.
Sources
Last reviewed: 19 October 2026.
