How to Tag a Container Image Using the `container image tag` Command

The container image tag command creates an additional reference (tag) for an existing container image without duplicating underlying layers by constructing an ImageTransfer request processed by the BuildImageResolver.

The apple/container repository provides a lightweight Container CLI for managing container images locally. When you need to assign an additional name or version identifier to an existing image, the container image tag command allows you to create these references efficiently. This guide explains the command syntax, internal implementation details, and practical usage based on the actual source code.

Understanding the container image tag Command

The container image tag sub-command generates a new reference for an existing container image without altering the original image data. According to the command reference in docs/command-reference.md, this operation creates an alias that points to the same underlying image layers as the original reference.

When executed, the command validates that both source and target arguments are supplied. It then constructs an internal request structure that maps the existing image reference to the new target reference.

Command Syntax and Usage

The basic syntax requires two arguments: the source image reference and the target reference.

container image tag <source> <target>

For example, to tag a local Alpine image with a new repository name:

container image tag alpine:latest myrepo/alpine:stable

You can also retag remote images without explicitly pulling them first:

container image tag registry.example.com/fido/web-test:1.0 registry.example.com/fido/web-test:latest

Internal Implementation with ImageTransfer

When you execute the tag command, the CLI builds an ImageTransfer request internally. As implemented in Sources/ContainerBuild/BuildImageResolver.swift, this structure carries:

• The source reference (ref)
• A tag derived from the image's digest
• Metadata containing the new target reference

The ImageTransfer initializer (lines 19-33) validates these fields and returns an imageTagMissing error if the tag metadata is absent (lines 41-44 in BuildImageResolver.swift).

The BuildImageResolver Component

The BuildImageResolver processes the transfer request by validating the presence of required metadata. If validation passes, the system records the new reference in the local image store while preserving the original reference untouched.

Testing and Validation

The integration test suite provides a helper method that demonstrates the exact CLI invocation. In Tests/IntegrationTests/Utilities/ContainerFixture+ImageHelpers.swift, the doImageTag method wraps the command:

func doImageTag(_ image: String, newName: String) throws {
    try run(["image", "tag", image, newName]).check()
}

This helper confirms that the CLI accepts the standard image tag subcommand syntax and validates that the operation succeeds.

Verifying Tagged Images

After tagging, both references point to the same underlying image data. Running container image list or container image inspect displays both the original and newly created tags, confirming they share identical digests.

Summary

• The container image tag command creates additional references without duplicating image data or modifying layers
• Internally, the command constructs an ImageTransfer request processed by BuildImageResolver in Sources/ContainerBuild/BuildImageResolver.swift
• Validation ensures the imageTagMissing error is thrown if tag metadata is absent from the request
• The test helper in Tests/IntegrationTests/Utilities/ContainerFixture+ImageHelpers.swift demonstrates the exact CLI invocation pattern
• Both original and new references appear in container image list output, pointing to the same underlying image

Frequently Asked Questions

Does tagging a container image duplicate the underlying storage?

No. Tagging creates a new reference pointing to the same image layers without copying data. The ImageTransfer mechanism in BuildImageResolver.swift only records the new reference in the local image store metadata, leaving the original reference intact.

What happens if I try to tag a non-existent image?

The CLI validates the source reference before constructing the ImageTransfer request. If the source image is missing or the tag metadata is absent, the resolver returns an imageTagMissing error as defined in BuildImageResolver.swift (lines 41-44).

Can I use the test helper in my own Swift code?

Yes. The doImageTag method in Tests/IntegrationTests/Utilities/ContainerFixture+ImageHelpers.swift demonstrates how to programmatically invoke the tag command. You can adapt this pattern for custom integration testing by calling the CLI with the ["image", "tag", source, target] argument array.

Is the container image tag command compatible with remote registries?

Yes. The command handles both local and remote images. If the source reference points to a remote registry, the CLI fetches the image if needed before applying the tag, as documented in the command reference and demonstrated in the integration test utilities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}