Skip to content

Artifact Management

Core (every shipped artifact passes through one of these). · prereq 03 (Containers · Docker & Podman), 15 (CI/CD) — CI/CD is what publishes into a registry, and containers are the artifact type most often stored there. · ~1 day (4 reference submodules — what an artifact registry is, container & package registries, versioning/immutability/retention, and signing & provenance). Reality check: this is the 80/20 on-ramp; real fluency (running a self-hosted Nexus/Artifactory instance, wiring SLSA provenance generation into a real pipeline) is built on the job.

Every CI/CD pipeline up to this point has quietly assumed a container image or package ends up somewhere durable after it's built. This module is where that assumption gets a name: an artifact registry is the versioned, durable home a build output lives in — so nothing downstream ever rebuilds from source and hopes the result matches what CI actually tested.

TL;DR — in 30 seconds:

  • Build once, reuse everywhere — a pipeline publishes an artifact to a registry a single time; every consumer (a deploy, another pipeline) pulls that exact stored artifact, never rebuilding it.
  • Container registries (GHCR, ECR, Docker Hub) hold images; universal repo managers (Nexus, Artifactory) hold images and language packages (npm, Maven, PyPI) behind one access-control model.
  • Tag immutability and retention policies keep a fixed reference actually fixed and stop a registry from growing forever; signing (cosign) and provenance (SLSA) let a consumer verify what's in it before trusting it.

Learning objectives

By the end, the junior can:

  • Explain why pulling a previously built artifact from a registry is more reliable than rebuilding it from source at deploy time.
  • Compare a container-only registry (GHCR, ECR, Docker Hub) to a universal repo manager (Nexus, Artifactory), and explain when the added system is worth it.
  • Explain the difference between a tag and a digest, and what tag immutability actually prevents.
  • Explain why a retention policy is necessary, and what it should never purge.
  • Explain, at a concept level, what signing (cosign) and provenance (SLSA) each verify — and what neither of them checks.
Do it with Claude

Pair, Do and Prove run in Claude Code, with the onboarding-tutor skill. Click a button to copy the exact prompt, then paste it into Claude Code in this repo.

1. Learn · acquire the concept

No external course — read this brief, then go deeper in the four reference pages below.

Mental model (20 minutes):

An artifact's path from build to trusted use has four concerns, and each one closes a gap the previous one leaves open:

flowchart LR
    A["Build once<br/>in CI/CD"] --> B["Push to a registry<br/>GHCR · ECR · Nexus · Artifactory"]
    B --> C["Tag & retain<br/>immutable tags · lifecycle policies"]
    C --> D["Verify before use<br/>signing · provenance (cosign · SLSA)"]
  • Build once — CI builds and tests one artifact; everything downstream pulls that exact artifact instead of rebuilding from source and risking a different result.
  • Push to a registry — the durable home is either a container-only registry (GHCR, ECR, Docker Hub) or a universal repo manager (Nexus, Artifactory) that also holds language packages.
  • Tag & retain — a tag is only a reliable reference if it can't be silently overwritten (immutability), and the registry needs a retention policy so it doesn't grow forever.
  • Verify before use — signing (cosign) proves an artifact hasn't been tampered with and names who signed it; provenance (SLSA) proves it was actually built by the expected pipeline from the expected source.

Go deeper: What an artifact registry is · Container and package registries · Versioning, immutability, and retention · Signing and provenance

Check yourself — a deploy pipeline rebuilds an image from source at deploy time instead of pulling a previously built one. What's the easy-to-miss risk?

The rebuild isn't guaranteed to produce the same bytes CI actually tested — a floating base image tag or an unpinned dependency can resolve differently between the two builds, even with an identical source commit. Pulling the artifact the registry already holds is what guarantees "what's deployed is what was tested."

Check yourself — what's the real difference between a tag like v1.2.3 and a digest?

A tag is a human-friendly, mutable-by-default pointer — nothing stops it from later being repointed at different content unless immutability is enabled. A digest is a content hash: it always means exactly one set of bytes, permanently, with no configuration required.

Done when: you can name, in order, the four concerns this module builds on each other (build once → push to a registry → tag & retain → verify before use), before moving to Pair.

2. Pair · passive → active

Drive the onboarding-tutor:

  • "Give me a CI/CD pipeline that rebuilds an image from source at deploy time and make me list every way that's unreliable compared to pulling from a registry."
  • "Quiz me on when I'd reach for a container-only registry (GHCR/ECR/Docker Hub) versus a universal repo manager (Nexus/Artifactory), and make me justify the choice for a team publishing containers, npm, and Maven artifacts."
  • "Give me a scenario where a production deployment references a mutable tag, and make me explain exactly what could go wrong."
  • "Walk me through designing a retention policy for a registry with thousands of images, and make me name what to keep versus purge."
  • "Quiz me on what cosign signing and SLSA provenance each actually verify — and what neither of them checks — for an image pulled in a deploy pipeline."

Common gotchas

  • Rebuilding an artifact at deploy time instead of pulling it. Fix: build once in CI, publish it, and always deploy the exact artifact that was pulled — never a fresh rebuild of "the same" source.
  • Deploying against a mutable tag like latest. Fix: deploy against a specific, immutable version tag or a digest — never a tag that's expected to keep moving.
  • Running a registry with no retention policy. Fix: unbounded storage cost and unpatched-image sprawl are both silent until they're expensive or exploited — set an age/count-based policy that always exempts anything a live deployment references.
  • Treating "it's signed" as proof an artifact is safe. Fix: signing proves integrity and origin, not the absence of vulnerabilities — pair it with scanning, and add provenance if you need to verify the build process itself.

Done when: you can explain why a rebuilt artifact isn't the same guarantee as a pulled one, and why a mutable tag is a production risk, without notes.

3. Do · produce an artifact

Exercise — a registry policy and verification writeup:

  1. Pick a build output from an earlier module (a container image or a package) as your subject artifact.
  2. Write registry-policy.md naming: which registry type it belongs in (container-only vs. universal repo manager, and a specific product), whether tag immutability is enabled, and a specific retention rule (e.g. "keep last 10 tagged releases, purge untagged images older than 30 days, never purge anything a live deployment references") with one sentence of rationale.
  3. Add a section explaining how a consumer would verify this artifact before using it: what a cosign signature check would confirm, and what an SLSA provenance check would additionally confirm — naming which pipeline stage (build, publish, or deploy-time) each check happens at.
  4. State one concrete thing that would go wrong if tag immutability were off, specific to something already running in production.

Done when: registry-policy.md names a specific registry product, a specific retention rule (not "some retention"), and explains signing and provenance as two separate questions with two separate answers.

4. Prove · understanding gate

Mandatory. Pass bar in the Socratic gate.

  1. Durability: Why doesn't rebuilding from source at deploy time give you the same guarantee as pulling the artifact CI already built and tested?
  2. Registry choice: Why did you pick a container-only registry or a universal repo manager for your artifact, and not the other?
  3. Immutability: What specifically breaks if the tag your deployment points to can be silently overwritten?
  4. Verification: What does a cosign signature check verify that an SLSA provenance check doesn't, and vice versa?
  5. Provenance: Which specific recommendation in your writeup did the tutor suggest, and how did you verify it was correct — by checking documented behavior, not by trusting the explanation?

Pass bar: you can defend every choice in your writeup by the specific guarantee it provides — not just "it's best practice" — and show how you verified a tutor-suggested detail against real documentation. "It works but I can't say why" = back to Pair.

5. Retain · fight forgetting

This module has no generated Anki deck yet. Recall by re-reading the four reference pages and re-running the Do exercise's writeup against a different artifact type (e.g. a package instead of a container image) until you can name the right registry, the right retention rule, and the signing-vs-provenance distinction from memory, unprompted. Done when you can name all three, cold, for any artifact type someone hands you.

Key takeaways

  • Build once, reuse everywhere — a pipeline publishes an artifact to a registry a single time; nothing downstream should ever rebuild it from source.
  • A container-only registry (GHCR, ECR, Docker Hub) suits container-only shops; a universal repo manager (Nexus, Artifactory) is worth the extra system when multiple artifact formats are in play.
  • A tag is a mutable-by-default pointer; a digest is the artifact's permanent, content-addressed identity — tag immutability is what makes a tag behave like the latter.
  • A retention policy keeps a registry bounded and free of unpatched sprawl — it should always exempt anything a live deployment references.
  • Signing (cosign) verifies an artifact hasn't been tampered with and who signed it; provenance (SLSA) separately verifies it was actually built by the expected pipeline from the expected source — neither one is a substitute for vulnerability scanning.

Go deeper — curated resources

Hand-picked external material to take this topic further — the best books, courses, talks, and writing. Cost is tagged Free, Free online (full text/course free on the web), or Paid.

  • Docs · GitHub Container Registry documentation — GitHub. Covers authenticating, pushing, pulling, and tagging images against ghcr.io. Free.
  • Docs · Amazon ECR — What is Amazon ECR? — AWS. The canonical overview of ECR's features, including lifecycle policies and image scanning. Free.
  • Docs · Sonatype Nexus Repository documentation — Sonatype. Documentation for the universal repository manager covering containers, npm, Maven, PyPI, and more. Free.
  • Tool · cosign — Sigstore. The tool for signing and verifying container images and other artifacts, including keyless signing. Free.
  • Docs · SLSA framework — Open Source Security Foundation / Linux Foundation. Defines the graduated levels of build-provenance integrity referenced in this module. Free.

Gate log (mentor fills on pass)

  • Date passed:
  • Passed by: / checked by:
  • Weak spots noticed (feeds system improvement):