Module ghcr 

Shared OCI-registry helpers: the published-component roster plus immutable manifest-digest resolution, registry-agnostic.

The cluster-upgrade path lives in two binaries — the operator CLI’s executor (polychrome upgrade --cluster) rolls the images, and the control plane’s mailbox originator captures the digests when it opens the approval ask. Both must agree on which images are published, where they live, and how a version’s tag resolves to an immutable sha256:… content address, so that logic lives here once rather than duplicated per binary.

Where the images live is configuration, not a constant. The open-source default is the public GHCR repositories; a private deployment overrides each component’s full image reference (registry host + repository) through the POLYCHROME_UPGRADE_IMAGE_* environment variables — for example a Google Artifact Registry path like us-east4-docker.pkg.dev/<project>/docker/polychrome-control-plane. The reference carries no tag; the tag is derived from the target version.

Resolution follows the OCI distribution flow: obtain a bearer token for the registry, GET the manifest, and read the registry-computed Docker-Content-Digest header — the canonical content address pinned onto the cluster. We never float a tag onto a running cluster. Which credential the token comes from depends on the registry host: a public GHCR repository uses the anonymous pull-token endpoint, while Google Artifact Registry / GCR uses a GCP OAuth access token.

Structs

Component

One published component the cluster upgrade rolls.

ImageRef

A resolved image reference — a registry host plus a repository, carrying no tag. The tag is derived per upgrade from the target version.

Enums

GhcrError

A digest-resolution failure.

RegistryAuth

How to authenticate a digest-resolution request against a registry host.

Constants

COMPONENTS

The Deployments an upgrade rolls.

STATE_COMPONENT_NAME

Component::name of the state plane, the component that rolls first.

Functions

auth_for

Pick the registry-auth strategy for a host.

http_client

Build the shared HTTP client used for registry round-trips (bounded connect and request timeouts, a polychrome/<version> user agent).

image_ref

Resolve a component’s image reference from the environment, falling back to its public GHCR default.

image_tag_for_version

Normalize a --version / release tag into the image tag published.

parse_image_ref

Split a full image reference string into its registry host and repository.

pinned_reference

Build the digest-pinned image reference from a resolved ImageRef and a content digest ({registry}/{repository}@{digest}).

resolve_digest

Resolve the immutable manifest digest for repository:tag against registry.