WSS
On this page
Deployment & DeliveryRequiredUpdated

Artifact registries and immutable builds

Artifact registries store compiled software components. Immutable builds guarantee that a compiled artifact never changes once pushed, ensuring the exact code tested is the exact code deployed.

Introduction

An artifact registry is a specialized storage system for compiled software packages, container images, and binary files. Unlike version control systems, which store source code, registries store the output of the build process.

Immutable builds dictate that once an artifact pushes to a registry, it cannot be modified or overwritten. Any change to the source code requires a new build, generating a new artifact with a unique version identifier.

Mental Model

Think of source code as a recipe and the artifact as the baked cake. Version control stores the recipe. The registry stores the cakes. Immutability means once you put a cake in the display case with a label, you cannot open the case, scrape off the icing, and replace it. If you want a different cake, you must bake a new one and give it a new label.

Operational Pattern

The CI/CD pipeline triggers a build phase. The build server compiles the source code, downloads dependencies, and packages the result into a deployable artifact.

The pipeline assigns a unique version identifier to the artifact, often combining the SemVer version, the Git commit hash, and a build number. The pipeline authenticates with the artifact registry and pushes the packaged file.

Subsequent deployment stages pull the artifact directly from the registry using its unique identifier. They do not recompile the source code. This guarantees that the binary executing in the production environment is bit-for-bit identical to the binary that passed the testing phase.

Failure Modes

Overwriting tags destroys reproducibility. If a registry permits users to push a new container image with an existing tag (e.g., v1.2.0), deployments become unpredictable. A node pulling v1.2.0 today receives a different binary than a node that pulled it yesterday.

Storage exhausts quickly. Storing a new binary for every commit consumes massive amounts of disk space. Without a retention policy, the registry eventually fills up and blocks new builds.

External registry outages halt deployments. If an application relies on a public artifact registry at runtime or during deployment, a network partition or service outage prevents scaling up new instances.

Security

Registries centralize the software supply chain. An attacker who compromises the registry can substitute a legitimate artifact with a malicious payload.

Sign artifacts cryptographically. The build pipeline should generate a digital signature for the artifact before pushing it. The deployment orchestrator must verify this signature before executing the binary.

Restrict write access. Only the automated build system should have permission to push to the production registry. Developers should not possess credentials to upload or overwrite artifacts manually.

Operational Guidance

Enforce immutability at the registry level. Configure the registry software to reject any PUT or POST request that targets a version identifier that already exists.

Implement automated retention policies. Configure the registry to automatically delete untagged artifacts, temporary builds, or artifacts older than a specific threshold, while permanently retaining artifacts currently deployed to production.

Use pull-through caches. If your deployment environment pulls artifacts from a remote or public registry, deploy a local caching proxy. This reduces network egress costs and protects against upstream registry outages.

Diagnostics

Compare file hashes. If you suspect an artifact was altered, download the binary from the registry and compare its SHA-256 hash against the hash recorded in the build pipeline logs.

Check registry access logs. Identify unauthorized attempts to push or delete artifacts by analyzing the audit trail of the registry service.

Monitor storage utilization. Set alerts for when the registry approaches its capacity limits, prompting a review of the retention policy.

Related topics

Sources & further reading