The artifact flow — from source to image to deployment

The artefact flow is the path from a source commit to a running container. It is the most forensically rich part of the reference architecture: the artefact leaves behind a trail of digests, signatures, and attestations the audit chain can walk backward. The trail is the artefact’s identity; without it, the running container is a black box whose provenance cannot be reconstructed.

The flow

flowchart LR
    A["Source commit\n(SHA)"] -->|"build"| B["Layered image\n(sha256:img)"]
    B -->|"cosign sign"| C["Signature\n(sha256:sig)"]
    B -->|"generate"| D["Provenance\n(SLSA)"]
    B -->|"scan"| E["SBOM\n(SPDX or CycloneDX)"]
    C --> F["Registry\n(digest-indexed)"]
    D --> F
    E --> F
    F -->|"pull by digest"| G["Manifest\n(image: sha256:img)"]
    G -->|"apply"| H["Running pod\n(imageID: sha256:img)"]

The flow has six transitions, each producing a signed artefact. The image’s identity is its digest; the signature’s identity is its digest; the provenance’s identity is its digest. Everything in the registry is addressed by digest; tags are pointers humans use to find digests.

The four artefacts at build time

The build plane produces four artefacts per build:

• Image. A layered OCI image whose topmost digest identifies the exact bytes. A rebuild from the same commit produces the same digest because layers are content-addressed.
• Signature. A cosign signature over the image digest, produced with a managed key or via keyless signing tied to the workflow.
• Provenance. An in-toto attestation recording builder, invocation, materials, subject. Subject is the image digest; materials include the source commit.
• SBOM. Software Bill of Materials in SPDX or CycloneDX, listing every package and version.

IMAGE="ghcr.io/acme/checkout:${GITHUB_SHA}"
cosign sign --yes "$IMAGE"
cosign attest --yes --predicate provenance.json --type slsaprovenance "$IMAGE"
cosign attest --yes --predicate sbom.spdx.json --type spdxjson "$IMAGE"

Each call pushes a new artefact signed by the same workflow identity and addressed by the image’s digest.

The digest is the identity

The registry holds two kinds of references: tags and digests. A tag is a mutable pointer; a digest is an immutable address.

REGISTRY=ghcr.io
REPO=acme/checkout
TAG=v3.2.7
DIGEST=sha256:b4ffde6502d1c5f7e3b9c1d8a8c2d3a4b5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0
crane manifest "${REGISTRY}/${REPO}:${TAG}" | jq .config.digest
crane manifest "${REGISTRY}/${REPO}@${DIGEST}" | jq .config.digest

The first returns the digest the tag currently points to; the second returns the digest at that exact address. They are equal at push time; the second remains correct forever.

SLSA Build L3 hardening

The artefact flow at SLSA Build L3 has three properties:

1. Provenance is non-forgeable. The build runs in a hardened runner whose identity is bound to the provenance attestation.
2. Provenance is generated automatically. No engineer hand-writes it; the attestation is the workflow’s output, signed at build time.
3. All build parameters are recorded. Materials list includes the source commit, dependency lockfiles, and build arguments.

L1 records the commit but signs nothing. L2 signs artefacts but the build runs on a shared runner. L3 signs from a hardened, isolated runner. The audit property improves at each level; L3 is the level at which the artefact identity can be reconstructed from provenance alone.

Why the registry is more than storage

The registry in the reference architecture is a participating component, not a passive disk:

• Immutability of digests. A digest cannot be overwritten; pushing the same digest is a no-op.
• Signature discovery. The registry serves the cosign signature alongside the image.
• Replication with identity. Cross-region replication carries the signatures.

A registry that stores images but does not serve signatures is a registry the deployer must verify out-of-band.

Production discipline

1. Pin by digest everywhere. Manifests, GitOps values, helm chart values, Terraform configuration
   • all reference by digest.
2. Sign at build time, verify at deploy time. A signature never verified is a signature not present.
3. Generate provenance automatically. Manual provenance is forgeable; attested provenance is not.

Cross-course references

• This course, Part LXX (SLSA) - the L1-L3 levels applied to the build plane.
• This course, Part XLVII (Signing) - the keys used by cosign.
• Kubernetes for Production Sysadmins - Parts XXXVIII-XL cover runtime image policy.

Quiz