Setting Up Skopeo for Container Image Copying and Inspection

Configuring Skopeo: why manual image transfer breaks delivery

When an image is transferred between registries manually — via an archive through an intermediate machine or by re-uploading from a local daemon — the supply chain breaks at the most inconspicuous point: between build and deployment.

The tag in the target container registry matches, but the contents differ — the copy was built from a different branch, with different dependencies, or in a different environment.

This is where typical failures come from. Image integrity is not confirmed by anything: there is no reference to the source manifest, and there is no way to prove that the verified artifact is what entered the environment. Rollback does not work — the previous image has been overwritten by the same tag.

Manual transfer also breaks what is not visible on a single environment: multi-architecture builds lose some platforms, signatures are not transferred, and a registry in an isolated environment has no external access. Each transfer becomes a separate operation that cannot be repeated with the same result.

Configuring Skopeo removes the manual operation itself.

Image copying goes directly from registry to registry, without a local daemon and without unpacking layers: the manifest is transferred along with the checksum, so the target environment ends up with exactly the artifact that passed the checks.

Inspection works before downloading: the manifest, layer composition, and checksum are visible in advance, and trust policies describe which registries and signatures are allowed. Access is configured once and reused in automation.

Next, we break down how this is addressed — from policies to transfer into isolated environments.

What automated image transfer between registries provides

Manual copying of images between registries almost always diverges from reality: someone transferred a tag, someone forgot a variant for a different architecture — and the test environment ends up with a different artifact than in production.

The error does not appear at rollout, but after hours of debugging non-reproducible behavior. Automation removes an entire class of such failures because an image is addressed not by tag, but by an immutable digest.

Skopeo copies an image directly between registries without starting a local daemon or taking up space for layers.

A configured transfer pulls the entire set of tags, preserves digests and variants for different architectures, so the same reference in any environment points to the same artifact.

A single source of images stops being an agreement between teams and becomes a property of the infrastructure.

What this changes measurably: registry synchronization runs on a schedule and takes minutes instead of hours of manual work, the share of manual operations drops to almost zero, and version divergence between environments stops being a cause of incidents.

Rollback is also predictable — the previous image remains in the registry and is substituted in the same way, without searching for “that same” tag.

Separately, we configure a mode in which only changed layers are transferred: repeated synchronization does not push the same data again. This is noticeable when registries are spread across sites and the channel between them is narrow.

Configuring Skopeo for multiple registries: comparison of modes

The mode of working with multiple registries is chosen not by command convenience, but by the access model: it determines whether the service account needs write permissions to the target or read access from the source is sufficient.

Direct transfer is a single copy command if the registries are reachable to each other over the network.

Before running it, the image is inspected: the tag may point to a manifest that has already changed, so the transfer goes by digest, and the result is compared with the source.

Mirroring defines a source–target pair and tag selection rules. Here, the service account only needs read access on the source and write access on the target, and permissions are granted for specific repositories rather than the entire registry.

Extra tags are removed by the retention policy — otherwise the mirror grows faster than the original.

The intermediate archive exports the image to a directory or a single file and loads it on the target side. It is applicable where there is no network between environments: the file is transferred on physical media, and integrity is confirmed by comparing the digest after import.

In all three cases, configuration comes down to one thing: a separate service account for each registry, minimum permissions for the task, and digest verification after the operation.

This access profile does not depend on the chosen image transfer mode and is reused in automation without rework.

Implementation stages: from registry audit to handover of regulations

Implementation begins not with editing configuration, but with inventory. As long as there is no registry map and no understanding of which images come from where, any copy automation simply reproduces the current mess in an accelerated form. Below is the sequence by which we guide the work.

1. Registry audit. We go through all sources and targets: addresses, access schemes, tag policies, storage volumes, history depth. The result is a table showing duplicates, abandoned repositories, and registries without backups.
2. Image transfer scheme. We determine flow direction and rules: what is mirrored in full, what only by latest tags, how we handle version divergence. We describe the rules in terms of registries, not individual commands — skopeo is a tool here, and the transfer scheme outlives it.
3. Access configuration. We move credentials into a separate authentication file, not the command line. For each registry — its own set of permissions: the build environment only needs read access to the source and write access to the target.
4. Integrity verification. We compare digests and manifests before and after copying, and check signatures if they are used. A copy without verification is not a transfer, but an assumption.
5. Implementation in the working environment. We put copying on a schedule, add error notifications and retries for network failures. Manual launch remains an emergency scenario, not the main one.
6. Handover of regulations. We hand over the registry map, scheme, configuration files, rollback procedure to the previous image, and instructions for the on-duty engineer. After that, maintenance does not require our participation.

Delivery package: configurations, schemes, policies, and regulations

After handover, the customer is left not with a set of scattered commands, but with a working environment for copying and verifying images on Skopeo — with clear points of responsibility. We hand over under an acceptance act:

• Configurations: registry trust policy file, authorization parameters, concurrency and operation retry values, ready profiles for each environment — with comments on non-obvious values.
• Registry schemes: map of sources and targets, list of synchronized repositories and tags, image promotion routes between environments, rules for mirroring external sources.
• Access policies: separate service accounts for read and write, minimum required permissions, token lifetimes and rotation procedure, restrictions on public registries.
• Inspection regulations: what is checked before publication — manifests, signatures, checksum, extra layers; which discrepancies block copying and how this appears in the log.
• Documentation: environment description, component placement scheme, instructions for typical operations — add a registry, change a tag, investigate an incident — and a troubleshooting table for common errors.
• Maintenance regulations: frequency of credential updates, cleanup of outdated tags, alert thresholds, escalation matrix with responsible roles.
• Rollback and acceptance plan: test scenarios in the test environment, acceptance criteria, and procedure for returning to the previous scheme without stopping deployment.

Case study: registry synchronization time reduced by a factor of three

The project has three sites: production environment, pre-production environment, and the customer’s isolated environment.

The same set of images was transferred between them weekly, and this was done manually: the image was pulled to an intermediate machine, the tag was reattached, and it was sent on.

Each release took about 40 minutes, and version divergence between environments was noticed only from service behavior.

What it was before

All transfer operations remained manual: the engineer kept a list of tags and manually marked what had already gone. Over a quarter — 5 incidents, all with the same cause: the pre-production environment ended up with an image from a different branch.

Rollback took about an hour because the needed version was searched for in the local cache and was not always found.

What was changed and what became

The transfer was moved to Skopeo: copying goes directly between registries, and the intermediate daemon and local cache are removed from the scheme.

The trust policy file allows only signed sources, site authorization is described in advance, and multi-architecture sets are transferred with a single command.

After transfer, the pipeline compares the source and target manifests by checksum and stops if they diverge.

Transfer time dropped from 40 to 13 minutes, the share of manual operations — from 100% to 10% (tag confirmation remained), version-related incidents — from five per quarter to zero. Environment desynchronization is now visible at the transfer stage, not after rollout.

How registry mirroring differs from direct image transfer

The difference is what exactly crosses the boundary between registries. Registry mirroring transfers the catalog as a whole — tags, manifests, layers — and keeps the target synchronized with the source.

Direct image transfer copies by one reference at a time and answers the task “deliver this image there.” These are two different modes with different maintenance costs, and confusing them is a typical reason why synchronization “seems configured” but the required tag is not on the site.

The Skopeo utility covers both scenarios and a third — offline operation: image inspection without loading into local storage, copying between registries, and export to a local archive on disk.

The choice of mode is determined not by the tool, but by topology: whether there is a direct network path between registries and whether catalog synchronization is needed rather than a single tag.

If there is a path and the tag composition must match — mirroring, otherwise you will be manually catching up with divergences. If only a few images are needed — direct transfer is cheaper to maintain and does not create unnecessary copies.

In an isolated environment there is no choice: the intermediate archive remains the only working path, and then it is critical to record exactly which digest was transferred, so that a different build is not assembled under the same tag on the target.

Technical doubts: what prevents transferring images directly

Direct image transfer between registries removes the need to build the same thing at each site, but before implementation the same questions repeat: how does this work in an isolated environment, what permissions should be granted, and what will happen to already running services.

Below are the answers that we verify on a test environment before any changes in the production environment.

What permissions are needed and does this grant excessive access?

A separate service user: read on the source repository and write on the target, no more. Credentials are taken from an access file with restricted permissions, rather than passed on the command line, so they do not remain in the call history.

After the transfer, access is revoked — this does not affect the operation of already copied images.

Will the signature be preserved and how to verify integrity?

The signature is tied to the content fingerprint, not the tag name, so transfer does not break it. After copying, we compare the fingerprints of the source and target: if they match, the bytes have not changed, and the trust policy will allow the image at startup. A mismatch is a signal to stop the rollout, not to push it through to the end.

Will services have to be stopped and how to roll back?

Running containers continue to run: image transfer does not touch running instances. Switching is done by tag — the new version is placed alongside, the old one remains in the registry.

Rollback is returning the previous tag and restarting, which takes minutes; the environment returns to its original state without rebuilding.

Let’s discuss the task: what data is needed for an estimate and plan

To come back with an estimate and plan rather than with clarifying questions, we need a minimum of initial data about the environment. In practice, this list covers almost all uncertainty: it already shows the scope of work, risks, and order of stages.

• Registry scheme: where we copy from and to — list of sources and targets, their type (internal, cloud, isolated), whether transfer between environments or constant mirroring is needed.
• Access and authentication: service accounts, tokens, read and write permissions, where secrets are stored and who manages them.
• Environment constraints: closed perimeter without external network, proxies, internal mirrors, requirements for certificates and trusted authorities.
• Image nomenclature: how many repositories and tags, which architectures, typical sizes, update frequency, who publishes.
• Tag and retention policy: naming rules, what counts as a release, how many versions we keep, and by what criterion we clean up outdated ones.
• Checks during transfer: whether vulnerability scanning is needed, signature confirmation, byte-by-byte comparison of manifests before and after copying.
• Target mode: manual launches, schedule or invocation from the build pipeline, whether error notifications and an operation log are needed.
• Time constraints: allowed work windows, requirements for rollback to the previous version and the depth of such rollback.

Describe the task as it stands now — that is enough for us to come back with an estimate and work plan: stages, configuration composition, and a list of what will be needed on your side.