Goal: Image owner can set a certain tag as immutable so that no one can overwrite or delete it in the future, so a tag can be trusted to be a stable reference.

Why is this important: While container image tags are floating and dynamic in nature, this is not always a desired. Specifically, when a build identifier that corresponds to a git commit sha/release/tag is to be used as a more human-friendly identifier, a tag is preferable to a SHA digest. However for that image tags should be immutable to keep the reference to the build stable. Other use cases involve regulatory or compliance requirements to programmatically avoid loosing or changing image tags without having the entire repository be read-only, which prevents pushes.

Acceptance criteria:

• only users with write permissions to the repository can set tags to be immutable
• only users with admin permissions to the repository can make a tag mutable again
• immutable tags cannot be overwritten
• immutable tags cannot be deleted
• immutable tags are not deleted by auto pruning
• manifests which have immutable tags pointing to them cannot be deleted
• immutable tags cannot be restored to via time machine (reversion)
• deletion of repositories containing immutable tags (or orgs containing such repos) is no impacted by this
• immutable tags cannot expire by default unless the repository or org owner decides that it should be allowed, if not allowed (default)
  • one cannot set an expiry date on an immutable tag
  • one cannot make a tag immutable if it has an expiry date
• manifests with immutable tags cannot have their labels changed (add or removed)
• new tags can be created off immutable tags, these are not immutable
• tags mutability can be toggled via the API
• tags can be made immutable by pushing a manifest with label (via Dockerfile / Containerfile called quay.immutable=true
  • adding the label via mutable labels in Quay, will not set the the immutability flag as it is a reserved label for push operations
  • the label cannot be removed as it is a built-in read-only label
  • this label cannot coexist with the quay.expires-after label, it will be ignored
• tag mutability settings via the API take precedence over labels
  • tags without a quay.immutable label can be set to immutable via the API
  • tags with the label quay.immutable=true can be set mutable via the API
• repositories with immutable tags cannot be converted to a mirror as the mirroring could fail to overwrite immutable tags
• orgs with repositories that have immutable tags cannot be converted to a cache org as the caching could fail to overwrite immutable tags
• tag immutability is only implemented for Docker v2s2/OCI specifications and formats