Principle:MaterializeInc Materialize Container Registry Publishing

Knowledge Sources	Immutable artifact versioning, content-addressed storage, container registry protocols, OCI distribution spec
Domains	Build Systems, Artifact Management, Container Registries, CI/CD, Immutable Infrastructure
Last Updated	2026-02-08

Overview

Content-addressed artifact publishing pushes built container images to remote registries using fingerprint-based tags, enabling deterministic retrieval and immutable versioning of build artifacts.

Description

Container registry publishing is the final stage of the build pipeline, where locally-built Docker images are pushed to one or more remote container registries so they can be consumed by other builds, CI jobs, or deployment systems. In a content-addressed build system, the image tag is derived from the cryptographic fingerprint of the image's inputs, which creates several powerful properties:

Immutability: Each fingerprint-based tag represents a unique, immutable snapshot of the image. Unlike mutable tags like latest or v1.0, a fingerprint tag can never be overwritten with different content (barring hash collisions). If the same tag already exists in the registry, it is guaranteed to contain the same image.

Idempotent publishing: Pushing the same image to the same fingerprint tag is a no-op (or a harmless overwrite with identical content). This means multiple CI jobs can safely attempt to publish the same image concurrently without coordination or conflict.

Dual-registry mirroring: For resilience and flexibility, images can be simultaneously published to multiple registries (e.g., Docker Hub and GitHub Container Registry) under the same fingerprint tag. This provides failover capability and accommodates different network access patterns.

Build-push atomicity: By using docker buildx build --push, the build and push operations are combined into a single command, eliminating the window between build completion and push initiation where a failure could leave an unpublished image.

Usage

Use content-addressed artifact publishing when:

• Making built images available to downstream consumers -- CI pipelines, other build targets, or deployment systems that need to pull a specific image version.
• Populating the remote build cache -- After building locally because a cache miss occurred, push the result so future builds (by any machine) can reuse it.
• Running the ensure() workflow -- The DependencySet.ensure() method checks if images are published and builds + pushes any that are missing.
• Mirroring images across registries -- Simultaneously publishing to Docker Hub and GHCR for redundancy.

Theoretical Basis

Immutable Artifact Versioning

Traditional artifact versioning uses mutable labels (version numbers, branch names, latest tags) that can point to different content over time. Content-addressed versioning eliminates this ambiguity:

Property	Mutable Tags	Content-Addressed Tags
Identity	Assigned by humans	Derived from content
Stability	Can change (re-tagged)	Immutable (same inputs = same tag)
Reproducibility	No guarantee	Guaranteed by construction
Concurrent safety	Requires coordination	Inherently safe (idempotent)
Cache validity	Must check for staleness	Always valid if present

The Ensure Pattern

The publishing workflow follows the ensure pattern -- a declarative approach where the system asserts what should exist and takes action only if the assertion fails:

for each image in dependency_set:
    if image.is_published():
        skip()                 # Already in the registry
    else:
        image.build(push=True) # Build and push in one step

This is convergent -- running the workflow multiple times always produces the same final state. It is also parallelizable -- independent images can be checked and built concurrently.

Dual-Registry Publishing

Publishing to multiple registries simultaneously provides:

• Fault tolerance -- If one registry is down, consumers can fall back to the other.
• Geographic distribution -- Different registries may have different CDN configurations, improving pull latency for global teams.
• Migration path -- When transitioning between registries (e.g., Docker Hub to GHCR), dual publishing ensures continuity.

The implementation achieves this by passing multiple -t flags to docker buildx build --push:

-t docker.io/{image_spec}
-t ghcr.io/materializeinc/{image_spec}

Buildx pushes to all tagged registries in a single operation, avoiding redundant layer uploads.

Authentication and Security

Publishing to authenticated registries (like GHCR) requires credentials. The pattern used is:

1. Check for a GITHUB_GHCR_TOKEN environment variable.
2. If present, invoke docker login ghcr.io with the token passed via stdin (avoiding command-line exposure).
3. The login session persists for the duration of the build, covering both the Docker Hub and GHCR pushes.

This ensures that credentials are never logged in command output or process listings.

Related Pages

Implemented By

• Implementation:MaterializeInc_Materialize_ResolvedImage_Build_Push