OCI Artifact

The OCI distribution specification decouples the storage and transport mechanism from the content type. An OCI Artifact is defined by its media type (e.g., application/vnd.cncf.helm.chart.config.v1+json) rather than a fixed image format. This allows registries to store Helm charts, SBOMs, SLSA Provenance attestations, WebAssembly modules, and OPA bundles as first-class objects. The registry treats all artifacts uniformly for operations like garbage collection and replication, while clients negotiate content handling based on the declared media type.

A critical extension enabling artifact graphs. The Referrers API allows clients to query an artifact's linked objects—such as finding all Cosign signatures or SBOM attestations for a specific image digest. This creates a queryable, in-registry graph:

• Signatures: Link a cryptographic signature to the signed manifest
• SBOMs: Attach a software bill of materials to the exact image it describes
• Vulnerability scans: Reference scan results alongside the scanned artifact This eliminates out-of-band metadata stores and keeps provenance data co-located with the artifact.

Every OCI Artifact is addressed by a SHA256 digest derived from its manifest content. This provides immutable, tamper-evident identification. Once pushed, the digest is a permanent fingerprint; any modification produces a new digest. This property is foundational for:

• SLSA Level 3 compliance: Non-forgeable build provenance
• Binary Authorization: Deploy-time policy enforcement based on exact digests
• Reproducible builds: Verifying that rebuilds produce identical digests Tags remain mutable pointers, but security-critical workflows pin to digests.

An OCI Image Index (or manifest list) is itself an OCI Artifact that references multiple platform-specific manifests under a single tag. This enables:

• Multi-arch container images: One tag resolves to linux/amd64, linux/arm64, and windows/amd64 variants
• Multi-artifact bundles: A single index can group a container image, its SBOM, and its signature as a deployable unit
• Fat manifest patterns: Grouping related artifacts for atomic promotion across environments The index is a JSON document containing an array of descriptors, each with a media type, digest, size, and optional platform constraints.

OCI Artifacts use the identical push, pull, mount, and delete workflows as container images. Tools like ORAS (OCI Registry As Storage) extend this to arbitrary content:

• oras push uploads any file with a custom media type
• oras pull retrieves artifacts by digest or tag
• Cross-registry copy: skopeo copy and crane copy replicate artifacts between registries This parity means existing registry infrastructure—authentication, RBAC, geo-replication, garbage collection—works without modification for non-image artifacts.

The artifactType field in the OCI manifest distinguishes artifact categories for registry-side filtering. Registries like Harbor and cloud providers expose this in their UI and API, allowing users to:

• Filter views: Show only Helm charts or only SBOMs
• Enforce policies: Apply different retention rules to signatures vs. container images
• Trigger automation: Fire webhooks when a new attestation is attached This metadata enables artifact-aware registry management without parsing the artifact content itself.

A unique, content-addressable SHA256 hash that immutably identifies a specific container image manifest or layer. Unlike mutable tags, a digest provides cryptographic verification of integrity. When you pull an image by digest, you are guaranteed to receive the exact same content every time. This is the cornerstone of secure supply chains, enabling deterministic deployments and preventing tag mutation attacks.

A cryptographically signed, verifiable statement about a container image, stored alongside it in the registry as an OCI artifact. Attestations can include:

• SBOMs (ingredient lists)
• Vulnerability scan results
• SLSA provenance (build records)
• Test results These signed statements enable policy-based admission control, ensuring only verified artifacts enter production.