Artefact and Container Registry Migration Playbook

Moving container images and packages to a new registry is easy to do and easy to do badly: tags are copied but signatures, SBOMs and attestations are left behind, deployments keep pulling from the old location, and push credentials scattered across pipelines stay valid long after the old registry should be gone. Organisations migrate artefact and container registries when a hosted registry is retired, when they consolidate several registries after a merger or cloud move, when they bring public image pulls behind an internal mirror, or when they change the platform that proxies and caches open source packages. This playbook covers the migration itself: what has to move, how to keep images byte-identical and verifiable, how to cut consumers over, how to rebuild push and pull identities, and how to retire the old registry safely. It is vendor-neutral and based on the OCI Distribution and Image specifications, NIST SP 800-190, NIST SP 800-204D, NIST SP 800-218 and SLSA. Registry hardening itself is covered in the Container Registry Security Guide.

Key takeaways

Copy by digest, verify by digest. An OCI digest identifies content exactly; a migration that preserves digests lets every consumer prove nothing changed.
Signatures and attestations are separate objects. They are stored as their own manifests linked to the image, so a tag-only copy silently drops them and verification fails or gets switched off.
Consumers decide when you are done. Deployment manifests, build files, runtime configuration and package resolver settings all name the old registry; inventory them before the copy.
Reissue push and pull credentials. Registry tokens live in pipelines, clusters and developer machines; replace them with scoped, federated identities and revoke the old ones at the source.
Do not import the junk. Stale, vulnerable and unowned images are a known registry risk; migrate what is in use and archive the rest.

What a registry migration actually moves

Object	Migration approach	Watch for
Image and artefact manifests and blobs	Copy with a tool that preserves manifests byte for byte, so digests are unchanged	Tools that re-compress layers or convert manifest formats, which changes the digest
Multi-platform image indexes	Copy the index and every platform manifest it references	Copying only the platform of the machine running the tool
Signatures, SBOMs, provenance and other attestations	Copy referrers for each digest, or the referrers tag schema where the source uses it	Target registry that does not support the referrers API; clients then need the fallback tag schema
Tags	Recreate pointing at the same digests; enable tag immutability for release tags	Tags moved in the source during the copy window
Language packages (internal libraries)	Republish the same files with their checksums and signatures	Version numbers reused with different contents
Upstream proxy and remote repository settings	Recreate the order in which internal and public sources are searched	Resolution order that lets a public package shadow an internal name
Access policies, robot accounts and tokens	Rebuild by intent from usage logs; reissue tokens	Broad push rights granted "for the migration"
Retention, immutability and scanning policies	Recreate as configuration and test	Retention rules that delete images still deployed
Audit logs of pushes and pulls	Export and archive for the retention period	History needed to trace which image ran where, lost with the old registry

Integrity: digests, signatures and referrers

The OCI Image specification defines a descriptor's digest as a content identifier that makes content addressable, and says retrieved content should be verified against the digest when it comes from untrusted sources. That is the core of a safe migration: if the digest of every image in the target matches the source, the content is the same.

Preserve digests: copy manifests and blobs without rewriting them. If a format conversion is unavoidable, treat the result as a new image that must be re-signed and re-attested by the build pipeline, not by the migration job.
Copy referrers: the OCI Distribution specification defines a referrers list as manifests with a subject relationship to a digest, queried with GET /v2/<name>/referrers/<digest>. Signatures, SBOMs and provenance are commonly attached this way. Copy them explicitly for each migrated digest.
Handle the fallback: where a registry does not support the referrers API, the specification requires clients to fall back to an image index pushed to a tag described by the referrers tag schema. If the source used the fallback and the target supports the API (or the reverse), test that your verification tooling finds the attestations in the target.
Verify, then switch: after copying, run the same signature and attestation verification your admission policy runs, against the target registry, for every image currently deployed.
Do not re-sign in the migration job: a job that can sign anything it copies becomes a way to launder unverified images. NIST SP 800-204D recommends signing only artefacts that pass policy, with signing keys protected in HSMs.

NIST SP 800-218 task PS.3.1 asks producers to archive integrity verification and provenance data for each release. If the old registry is the only place those referrers exist, copying them is a release obligation, not a convenience. See SBOM operations and the Code Signing Security Guide.

Choosing what to migrate

NIST SP 800-190 names stale images in registries as a risk, because registries accumulate old, vulnerable versions that raise the chance of deploying one, and recommends pruning unsafe images and referencing immutable, versioned names rather than latest. A migration is the obvious moment to apply that.

Image or package class	Approach	Reason
Currently deployed in any environment	Migrate with referrers; verify	Needed for restarts, scaling and rollback
Recent releases within the rollback window	Migrate with referrers	Needed to roll back after cutover
Older releases under a retention or legal obligation	Archive to cold storage with digests and referrers; do not serve	Kept for investigation, not for deployment
Development and feature-branch builds	Do not migrate; rebuild on demand	Volume without value
Images with no owner and no recent pulls	Do not migrate; record and archive or delete	Stale images are a known registry risk
Cached copies of public images and packages	Let the target cache refill through its proxy	Avoids importing cached content of unknown origin

Use pull logs from the old registry and the image references in running workloads to decide which class each repository is in. Whatever you choose not to migrate, write down so that a later failed pull is a known event.

Package repositories and dependency resolution

Registries that serve language packages add a risk container registries do not: the resolution order between internal and public sources. If the new configuration searches a public index before, or alongside, the internal one, a public package with an internal name can be pulled instead. See the Malicious Package and Dependency Confusion Guide.

Reserve internal names: use scopes or namespaces for internal packages and configure the target so those names never resolve from a public source.
Keep checksums stable: republish the same files so lock files and checksum databases still match. A version number with different contents breaks reproducibility and hides tampering.
Curate the proxy: NIST SP 800-204D recommends verifying the provenance of ingested components and caching or curating packages for preferred use, and being able to block artefacts from builds based on scan results. Recreate those block rules before switching builds.

Where identity fits

NIST SP 800-190 recommends that all access to registries holding proprietary or sensitive images require authentication, that write access always require it, and that push rights be scoped to the repositories each party is responsible for. Most registry identities are non-human: pipeline push credentials, cluster pull secrets, node identities, scanning tools and replication jobs.

Identity	Target pattern	Revoke in the old registry when
Pipeline push credentials	Federated or short-lived token per job, push to one repository path	The pipeline has pushed and the deployment pulled from the target
Cluster and node pull credentials	Workload or node identity with pull-only rights, scoped by environment	No pulls from that cluster appear in old registry logs
Developer access	Single sign-on with pull rights; push only through pipelines for release repositories	Cutover announced and old endpoint frozen
Scanners and replication jobs	Read-only service identity per tool	Tool reconfigured to the target
Migration job	Read on source, write on target, per wave, no signing rights	Each wave completes

Registry tokens with wide reach are high-value secrets. In the exposed Kubernetes secrets case involving an SAP artifact repository key, a single repository credential reportedly reached tens of millions of artefacts. See the Artifactory Tokens Security Guide for token types in one common platform.

The phased playbook

Inventory: repositories, image and package counts, referrers per image, tags in use, push and pull identities, and every consumer reference (deployment manifests, build files, base image lines, package resolver configuration, runtime mirror settings). Use 90 days of pull logs (our recommendation) to find consumers no one listed.
Design the target: repository layout by team and environment, tag immutability for release repositories, retention rules, scanning on push, encrypted connections only (NIST SP 800-190 recommends tools connect to registries only over encrypted channels), and identity patterns from the table above.
Pilot: migrate one application's images with referrers; deploy it from the target through the normal admission policy; perform a rollback to an older migrated image.
Copy in waves: copy by digest, then verify digests, signatures and attestations in the target. Track per repository: copied, verified, consumers switched.
Switch writers first: point pipelines at the target so new releases are pushed there. Optionally push to both during the overlap, but sign and attest once, in the build pipeline.
Switch readers: update deployment references to the target, ideally pinned by digest. Watch the old registry's pull logs fall to zero per consumer.
Freeze the old registry: make it read-only and alert on any push. Keep it readable through the rollback window.
Decommission: archive logs and any retained images with their referrers, revoke every old token at the registry and any external identity provider, remove network routes and DNS names, then delete storage following NIST SP 800-88.

Rollback: until the old registry is decommissioned, rollback means reverting consumer references to the old registry, which still holds identical digests. Keep it readable until every consumer has run on the target through at least one full release cycle (our recommendation). Small organisations with one registry and a few dozen images can copy and switch in a single window; large estates need waves, per-repository tracking and a pull-through period where the target proxies the old registry for anything not yet migrated.

Detection and measurement

Metric or signal	Why it matters	Target (our recommendation)
Deployed images whose digest exists in the target	Readiness to switch readers	100% before freeze
Migrated images that pass signature and attestation verification in the target	Referrers were copied	100% of deployed and rollback images
Pulls from the old registry by consumer	Finds remaining readers	Falling to zero before freeze
Pushes to the old registry after writer switch	A pipeline was missed, or misuse	Zero; alert on any
Old registry tokens still valid	Revocation progress	Zero at decommission
Internal package names resolved from public sources	Dependency confusion exposure in the new configuration	Zero

NIST SP 800-190 recommends auditing write access and read access to sensitive images. Keep both registries' audit logs together for the whole migration so that an unexpected pull or push can be traced to an identity.

Common failure patterns

Tag-only copy: images arrive without signatures or attestations; admission policy fails, and someone switches verification to audit mode "for now".
Digest drift: the copy tool rewrote manifests, so pinned digests in deployment files no longer resolve and teams replace them with mutable tags.
Secrets carried in layers: old images that embedded credentials are migrated as they are. Secrets in image layers are a known exposure, as the study of secrets in Docker Hub images found. Scan before migrating and rotate anything found. See How to find hard-coded secrets in container images.
Forgotten pull secrets: clusters keep old registry credentials, and the old registry is kept alive because something still pulls from it.
Resolution order change: the new package proxy searches public sources first and an internal package name is shadowed.
Retention deletes rollback images: a default retention rule in the target removes the images needed to roll back.

Framework mapping

Activity	NIST SP 800-53 Rev 5	NIST CSF 2.0	Other
Digest and signature verification after copy	SI-7, SI-7(6), CM-14	PR.PS-06	OWASP CICD-SEC-9
Copying provenance and SBOM referrers	SR-4	PR.PS-06	SSDF PS.3.1, PS.3.2; SLSA Build track
Push and pull identity rebuild	IA-5, AC-6	PR.AA-05	NIST SP 800-190 section 4.2.3
Encrypted registry connections	SC-8	PR.DS-02	NIST SP 800-190 section 4.2.1
Inventory of repositories and consumers	CM-8	ID.AM-02
Registry audit logging	AU-2, AU-11	DE.CM-09
Threats the migration must not reopen	SR-4, SI-7	PR.PS-06	ATT&CK T1525, T1195.002

Practitioner checklist

Inventory repositories, referrers, tags, identities and every consumer reference.
Decide per class what to migrate, archive or leave behind, and record it.
Copy by digest with referrers; verify digests, signatures and attestations in the target.
Never give the migration job signing rights.
Recreate tag immutability, retention, scanning and encrypted-only connections before cutover.
Reserve internal package names and test resolution order against public sources.
Switch writers, then readers, pinned by digest where possible.
Reissue push and pull credentials as scoped, federated identities; revoke old tokens at the source.
Scan migrated images for embedded secrets and rotate anything found.
Freeze, archive and delete the old registry on a dated plan.

Artefact and container registry migration playbook: moving platforms without losing control