Docker Retag

🐳 Retag an existing Docker image without the overhead of pulling and pushing

Motivation

There are certain situation where it is desirable to give an existing Docker image an additional tag. This is usually acomplished by a docker pull, followed by a docker tag and a docker push.

That approach has the downside of downloading the contents of every layer from Docker Hub, which has bandwidth and performance implications, especially in a CI environment.

This tool uses the Docker Registry API to pull and push only a tiny manifest of the layers, bypassing the download overhead. Using this approach, an image of any size can be retagged in approximately 2 seconds.

Installing

From source

You can use go get to install this tool by running:

$ go get -u github.com/MagnaXSoftware/docker-retag

Precompiled binary

Alternatively, you can download a static release binary.

Usage

Setup

Since docker-retag communicates with any Docker Registry API, you must first export your account credentials into the working environment. These are the same credentials that you would use during docker login.

$ export DOCKER_USER='joshdk'
$ export DOCKER_PASS='hunter2'

The credentials must have both pull and push access for the Docker repository you are retagging.

If you wish to use a third-party registry (not Docker Hub), set the DOCKER_REGISTRY environment variable:

$ export DOCKER_REGISTRY='https://url.of.my.registry/'

Make sure to include the trailing / in the url of the registry.

Examples

This tool can be used in a few simple ways. The simplest of which is using a source image reference (similar to anything you could pass to docker tag) and a target tag.

Referencing a source image by tag name.

$ docker-retag joshdk/hello-world:1.0.0 1.0.1
  Retagged joshdk/hello-world:1.0.0 as joshdk/hello-world:1.0.1

Referencing a source image by sha256 digest.

$ docker-retag joshdk/hello-world@sha256:933f...3e90 1.0.1
  Retagged joshdk/hello-world@sha256:933f...3e90 as joshdk/hello-world:1.0.1

Referencing an image only by name will default to using latest.

$ docker-retag joshdk/hello-world 1.0.1
  Retagged joshdk/hello-world:latest as joshdk/hello-world:1.0.1

Additionally, you can pass the image name, source reference, and target tag as seperate arguments.

$ docker-retag joshdk/hello-world 1.0.0 1.0.1
  Retagged joshdk/hello-world:1.0.0 as joshdk/hello-world:1.0.1

$ docker-retag joshdk/hello-world @sha256:933f...3e90 1.0.1
  Retagged joshdk/hello-world@sha256:933f...3e90 as joshdk/hello-world:1.0.1

In all cases, the image and source reference must already exist in the docker registry.

License

This library is distributed under the MIT License, see LICENSE.txt for more information.