Goal: Image owner can set a 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:

• users can set individual tags to be mutable/immutable explicitly via API and UI
• users can express repository-level and organization-level policies with regular expression patterns that define which tags are immutable (via API and UI)
  • users can express multiple such policies which are processed with a logical OR operation (i.e. the first matching policy wins)
  • Organization-level immutability policies apply to all repositories within that organization.
  • The UI should provide a way for users to search for tags using a regex and perform a bulk action to set them as immutable, allowing users to apply new policies to existing content in a controlled, one-off operation.

• 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 not impacted by this
• Users can set an expiration date on an immutable tag. The system should treat immutability (preventing content change) and expiration (scheduling deletion) as independent properties.
  • Users can make a tag with an existing expiration date as immutable.
  • The "quay.immutable=true" label can coexist with the "quay.expires-after" label.  When both are present during a push, the tag will be created as both immutable and expiring.
  • A new "organization-level" config/setting is introduced to optionally disallow expiration for immutable tags.

• 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 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
• When a tag is pulled through a caching proxy, its immutability status from the upstream registry should be preserved. 
  • If the upstream tag is immutable, the cached tag in Quay should also be immutable.