I mostly self-host software using docker compose. I tend to lock down image versions to a major & minor semver version (like postgres:18.4), and avoid using the latest tag. Security is not my main motivation, I want to make sure I don’t accidentally pull in a breaking change or incompatible dependency during an update.

However, it’s sometimes tricky to locate the right version tags to achieve this.

The following questions can be hard to answer:

• What are the other semver-style tags are shared by the latest release image currently? In which variants does it exist?
• In case I did happen to use a latest tag somewhere a while ago, but it has now been superseeded, what is the most narrow semver-style tag that points to the same image SHA? Someone on Reddit asked the same. This can be useful to look up changelogs since the last update.

These questions are sometimes hard to answer, because as far as I’ve seen, semver-style tags are applied to images entirely by convention, they are not required by the specification of the Docker (or OCI) image tag. How user-friendly the description of available tags is depends on the written documentation of the project.

Registries themselves don’t help much. The Docker Hub web /tags listing (example) can sort either by “Newest/Oldest” (build time) or “A-Z” or “Z-A”. You can not sort by semver, because semver is not foreseen in the specification. Newer patch builds of older major versions are often built after the latest stable release, and there are often very many releases, so this is not an easy way to find answers to the above questions. The GHCR does not even have any sorting options (example).

What I would like to have

A CLI tool that easily answers these questions.

# Where tag is a SHA or a tag like `latest`
$ docker-tag-finder postgres:latest

The following tags are shared by `latest`:
- 18.4
- 18.4-trixie
- 18
- 18-trixie
- trixie

Note that for this example, Postgres’ Docker image actually does have good & simple written documentation on the available tags. But this is often not the case.

Implementation notes

In the past I’ve already attempted some scripts found online to help with answering (some of) these questions. What I remember is that they had to loop, slowly, through all tags published, ever to potentially find the needed tags. Often, tags are also “overwritten” (they point at a new image, like git branches), and the link between the tag you used and the image you have disappeared. and that loads of excess information had to be fetched depending on the question. This might be an unavoidable due to the limited query capabilities of of docker registries.

It could take seconds or even minutes, and one should be careful to not hit rate limits. The CLI should probably show some meaningful indication of progress.