Artifact Registry

When your CI pipeline finishes compiling code, it produces files you actually ship: a Docker image, a compiled JAR, a Python wheel, an npm tarball, a .deb package. These are called artifacts. An artifact registry is the server that stores them, tags each one with a version, and hands them out when something asks for a specific name and version.

Think of it as a package warehouse with an inventory system. Git stores your source code; the registry stores the compiled result of building that source. You push an artifact in after a build, and later you pull it out during deployment, during another build that depends on it, or when a teammate runs npm install.

A single registry usually speaks several protocols at once. The same Artifactory or Google Artifact Registry instance can act as a Docker registry, a Maven repository, an npm registry, and a PyPI index, each behind its own URL path so the standard client tools talk to it without modification.

Most modern artifacts are content addressed. A Docker image is a manifest that lists layers, and each layer is identified by a SHA256 digest of its contents. When you push an image, the client uploads only the layers the registry does not already have, then uploads a small manifest pointing at them. Because layers are deduplicated by digest, ten images built on the same base layer store that base only once.

Tags like v1.4.0 or latest are mutable pointers to an immutable digest. The digest never changes once content is stored, which is why production systems often pin to a digest (image@sha256:abc...) instead of a tag, so a rebuild of latest cannot silently change what runs.

Registries expose a standard HTTP API. The OCI distribution spec defines endpoints for blobs and manifests; Maven uses plain GET and PUT over HTTP; npm uses its own JSON metadata format. The registry layers access control, quotas, and retention on top: who can push to a repo, how many old versions to keep, and which artifacts to garbage collect once nothing references them.

Many registries also run as proxy caches. You point npm or pip at the registry, and on a cache miss it fetches from the public source, stores a copy, and serves it. The next build pulls from the local cache, which protects you from a public package being deleted or going offline.

Use a registry the moment more than one machine needs the same build output. CI builds an image once and pushes it; staging and production both pull that exact image, so you test and ship the same bytes. Without a registry teams rebuild on each box and drift apart, or pass artifacts around by hand.

A private registry is worth running when you have proprietary code, need to control supply chain risk, or want fast pulls inside your own network. The cost is operational: storage grows quickly because image layers and old versions pile up, so you need retention policies and garbage collection or bills balloon. A registry is also a hard dependency in your deploy path, so it needs high availability and a pull-through cache for the public ecosystems you depend on.

The main trade-off is convenience versus control. Public Docker Hub is free and zero setup but has pull rate limits and you do not own uptime. A managed cloud registry like Google Artifact Registry or Amazon ECR removes the ops burden but ties you to that provider and charges for storage and egress. Self-hosting Artifactory or Harbor gives full control and on-prem speed at the price of running the service yourself.

A team building a payments service runs GitHub Actions on every merge to main. The job builds a Docker image, tags it payments-api:git-sha-3f9a2c1, and pushes it to Amazon ECR. The push uploads only the application layer because the Python base layer already exists in the registry from earlier builds, so it finishes in a few seconds.

The deploy step then updates the Kubernetes Deployment to reference payments-api@sha256:... by digest. Every node that schedules a pod pulls that exact image from ECR. Because the cluster lives in the same AWS region, pulls are fast and free of public rate limits.

A retention rule keeps the last 30 tagged images and deletes untagged ones after 14 days, so storage stays bounded even though dozens of builds happen daily. If a rollback is needed, the operator points the Deployment at last week's digest, which is still in the registry, and the old version is running again in under a minute.