In GitLab 19.4, a pipeline run by a Maintainer overwrote the release image tag v2.3.0; would protected or immutable container tags have prevented it, and how?
answer
- who may push against may anyone overwrite
- role thresholds versus no exceptions
- Free versus Ultimate
- the existing-tag check comes second
basics
~20 sA protected tag rule stops it only if its minimum push role is above Maintainer; an immutable tag rule (Ultimate, generally available since GitLab 18.10) stops anyone from overwriting or deleting an existing matching tag.
solid answer
~50 s**Protected container tags** (all tiers, generally available in GitLab 17.11) restrict who may push and delete tags matching an RE2 pattern: **Minimum role allowed to push** and **Minimum role allowed to delete** can be Maintainer, Owner or Administrator. With push set to Maintainer, the overwrite still succeeds; set to Owner, it is blocked for the Maintainer but not for an Owner. **Immutable container tags** (Ultimate, generally available in 18.10) mean that once a matching tag exists, nobody can update or delete it. On push, GitLab checks the protected rule first; if the tag already exists, it then checks immutability. So for release tags like `v2.3.0` an immutable rule on a semantic-version pattern is the real fix, with protected rules deciding who may create them. Both need the registry metadata database on GitLab Self-Managed, and both are skipped by cleanup policies.
go deeper
Recall that protected tags limit who may push or delete, while immutable tags stop anyone from changing an existing tag. Know that immutability is an Ultimate feature.
Explain the push evaluation order, the minimum-role settings, the Owner-only creation of immutable rules, and the release in which each feature became generally available.
Combine the rules so release tags are both restricted and unchangeable, keep moving tags out of immutable patterns, and account for the metadata database and JWT propagation delay.
Decide which artifacts must be provably unchanged after release and enforce that in the registry instead of in pipeline discipline, weighing the Ultimate requirement against the audit value.
## The two features answer different questions By default anyone with the Developer, Maintainer or Owner role can push and delete any tag in a project's container repositories. A tag is a movable name, so a re-run pipeline that pushes `v2.3.0` again silently points it at new content. GitLab offers two rule types that look alike and are not: | | Protected container tags | Immutable container tags | |---|---|---| | Question answered | **who** may push or delete a matching tag | **whether** an existing matching tag may change at all | | Tier | Free, Premium, Ultimate | Ultimate | | Generally available | GitLab 17.11 | GitLab 18.10 | | Who creates the rule | Maintainer or Owner | Owner | | Settings | pattern, **Minimum role allowed to push**, **Minimum role allowed to delete** | pattern only; rules can be created and deleted, not updated | | Exceptions | users at or above the minimum role | none | Both use **RE2** patterns of at most 100 characters, both are created under **Protected container tags** in the project's package and registry settings (immutability is a **Protection type** there), the documentation caps each kind at five rules per project, and when several rules match, the most restrictive applies. ## How a push is evaluated 1. **Protected tag check.** Does the pusher have the minimum role for this pattern? If not, the push is denied. 2. **Does the tag already exist?** If not, it is created. 3. **Immutable tag check.** If it exists and matches an immutable pattern, the push is denied; otherwise it is overwritten. Applied to the question: - A protected rule `v.*` with push set to **Maintainer**: the Maintainer's pipeline passes and overwrites the tag. - The same rule with push set to **Owner**: the Maintainer is stopped, but an Owner could still overwrite it. - An immutable rule `v\d+\.\d+\.\d+`: the first push of `v2.3.0` succeeds; every later push or delete of it fails for everyone. So immutability is the control that guarantees a released tag keeps its content, while protection decides who may publish release tags in the first place. They combine well: protect `v.*` for Maintainers and above, and make the semantic-version pattern immutable. ## Where they fit with the rest of the registry - **Cleanup policies** skip both protected and immutable tags, so retention never removes a release. - **Protected container repositories** (generally available in 17.8) protect whole repository paths with wildcards and a **Minimum access level for push**; deploy tokens cannot push to them at all. - **Package protection rules** do the equivalent for packages: a name pattern, a package type, and minimum access levels for push and delete; deploy tokens cannot push protected packages. - **Manifest deletion** through the registry API, which would remove every tag pointing at a manifest, is refused while the project has immutable rules, and restricted under tag protection. ## Prerequisites and timing - **GitLab Self-Managed** needs the container registry **metadata database** for both features; GitLab.com already uses it. The legacy metadata storage was deprecated in GitLab 18.5, so new registry features assume the database. - Rule changes propagate through the registry's JWTs, so a change can take up to the token duration to apply: 5 minutes by default, 15 minutes on GitLab.com. - An image that has tags cannot be deleted by a user whose role is below a delete threshold in any tag protection rule, even if no pattern matches. ## Release history to know | Release | Change | |---|---| | 17.9 | protected container tags introduced as an experiment | | 17.11 | protected container tags generally available | | 18.1 | immutable tags introduced as an experiment | | 18.2 | immutable tags enabled on GitLab.com as beta | | 18.10 | immutable tags generally available | ## Choosing for the scenario - Release tags that customers deploy: **immutable**, on a pattern that matches only semantic versions, so moving tags such as `main` or `latest` stay usable. - Who may cut a release: **protected**, with push at Maintainer or Owner. - Pipelines that must republish: give them a new tag, never the same one, and deploy by digest when exactness matters. - Changing an immutable pattern later: rules cannot be edited, so an Owner creates a replacement rule and then deletes the old one; plan the pattern before the first release.
- In GitLab, why should `latest` or `main` usually not match an immutable tag rule?Those tags exist to move: each build repoints them. An immutable rule would make the first push the last, so every later pipeline pushing `latest` would fail. Keep immutability for version tags that must never change, and use protected rules if moving tags need a restricted set of pushers.
- In GitLab, can a deploy token with `write_registry` push to a repository covered by a protected container repository rule?No. Deploy tokens cannot push to protected container repositories regardless of their scopes. The push needs a role that meets the rule's **Minimum access level for push**, so pipelines publishing there must use the job token of a sufficiently privileged user or another user-backed credential.
- In GitLab Self-Managed, a team creates a tag protection rule and pushes still succeed for a few minutes. Why?Rule changes reach the registry through its JWTs, so they apply only when current tokens expire: 5 minutes by default on Self-Managed, longer if an administrator raised the duration. Most clients request a fresh token per operation, but a custom client may hold one for its full validity.
- A protected tag rule makes a matching tag unchangeable for every user.
- Immutable tags still let Maintainers overwrite a tag if they have the push role.
- Immutable container tags are available on every tier.
- An immutable rule blocks the first push of a matching tag.
- Cleanup policies remove protected tags once they match the remove regex.
Assumes GitLab 19.4. Protected container tags became generally available in 17.11 on every tier; immutable container tags became generally available in 18.10 on Ultimate; Self-Managed needs the registry metadata database for both.