Enforce tag immutability at the Docker Hub repository level

[leighmcculloch]

What problem does your feature solve?

Today, the immutability of published image tags (:<cli>, :<cli>-rust<rust>, per-arch tags, etc.) is enforced only inside the publish workflow — see the "skip-with-warning, not fail-on-overwrite" behavior added in #3. That is workflow-side protection: it depends on the workflow being the only thing that ever pushes to this repo, and on that check never being bypassed (e.g. by a maintainer running docker push locally, by a future change to the workflow that drops the check, or by a compromised CI credential).

We should enforce the same property at the registry itself, so the trust property — "this tag means the same content forever" — has no opt-out even if the workflow is bypassed.

Docker Hub supports this via immutable tags on the repository: once a tag is pushed, the registry refuses any subsequent push to the same tag.

What would you like to see?

Configure docker.io/stellar/stellar-cli on Docker Hub so that:

• All tags are immutable by default — once pushed, they cannot be overwritten.
• The :latest tag is exempt — it is intentionally a moving alias that gets re-pointed each release.

Concretely, this means setting an immutable-tag rule on the repository that matches every tag except latest (e.g. via Docker Hub's tag immutability rules, with latest carved out).

Refs

https://docs.docker.com/docker-hub/repos/manage/hub-images/immutable-tags/

[leighmcculloch]

This probably means opening a ticket with @stellar/ops-team, but before that, we probably need to consider #9, so I created an issue here instead.

[fnando]

Tag immutability a very limited feature: we can either allow everything to be mutable, everything to be immutable (including :latest), or by regex. The regex is very basic and don't accept negative matchers, so that would need to be something like ^\d.+$; that is, if it starts with a number, it's immutable. Everything else is allowed and mutable.

I guess that's good enough?

[leighmcculloch]

👍🏻 I think that's good enough.

[fnando]

i think we should make the cli version tag mutable as well (e.g. 26.0.0), because we may update the rust version due to a new release, so you you get 26.1.0 + 1.96.0 as 26.1.0, then 26.1.0 + 1.96.1 as 26.1.0 later on too.

Based on #9 tag strategy, the regex must allow/reject based on the list below:

:latest (movable)
:<stellar cli version> (movable)
:<stellar-cli>-<rev>-rust<rust version>-<distro> (immutable, multi-arch)
:<stellar-cli>-<rev>-rust<rust version>-<distro>-<arch> (immutable)

[fnando]

closing this. We've decided to make tags mutable for simplicity. We'll publish:

• :latest
• :<cli-version> (e.g. :26.0.0)
• :<cli-version>-rust<base image> (e.g. :26.0.0-rust1.95.0-slim-trixie, multi-arch)
• :<cli-version>-rust<base image>-<arch> (e.g. :26.0.0-rust1.95.0-slim-trixie-arm64)

All versioned tags may point to different base images over time in case rust's base image updates, like a security fix. The builds.json file is the ultimate source of truth of all the digests we've used (once #20 is merged).