Re-tagging docker images easily

2 February, 2026 at 15:07 -0500

If you’ve configured CI to automatically build images, you’ve probably encountered some similar problems:

You want to automatically build docker images for the project every time the branch head changes, but you only want to change the latest tag if a new version is released (or only if the master branch is updated).
You build the image, tagging it with the commit-ID, then run tests on it, and update the latest tag to point to it if the tests pass.

Under normal circumstances, you can easily do so using the docker tag command. Unfortunately, that comes with some downsides: it requires 1) a running docker daemon and 2) downloading the full docker image prior to re-tagging.

Given that we want to re-tag (or rather add a new tag) to an image that exists already on the remote, a better solution emerges. Rather than downloading the full image, only download the manifest, then upload it to the new tag. Given that all the layers are the same, this will effectively re-tag the image without the costly download.

docker-retag

docker-retag is a small binary program that will do this retagging.

The easiest ways to use it are either the pre-built binaries (covering a wide range of platforms) or the docker image (useful for CI uses). If you’d rather build the source yourself, it only requires go 1.25 or newer.

In either case, using it is quite simple.

If your registry requires authentication, set the DOCKER_USER and DOCKER_PASS environment variables:

$ export DOCKER_USER='my_docker_user'
$ export DOCKER_PASS='hunter2'

If you are not using Docker Hub, also set DOCKER_REGISTRY to the URL of your registry:

$ export DOCKER_REGISTRY='https://my.custom.registry/'

Then, you simply call docker-retag with the "repository" (name of the image) and the new tag to add:

$ docker-retag whoami:v1.0 new-tag-i-want-to-add
$ # or, separating the repository and original tag
$ docker-retag whoami v1.0 new-tag-i-want-to-add
$ # or, using the default original tag (latest)
$ docker-retag whoami new-tag-i-want-to-add
$ # or, using a sha256 digest
$ docker-retag whoami@sha256:933f...3e90 1.0.1

As a Docker Image

To use docker-retag as a docker image, it’s a similar incantation.

$ docker run -it -rm -e DOCKER_REGISTY='https://my.custom.registry/' -e DOCKER_USER='my_docker_user' -e DOCKER_PASS='hunter2' ghcr.io/magnaxsoftware/docker-retag:latestwhoami:latest new-tag-i-want-to-add