skip to content

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?

level: seniorimportance: nice to knowfreq 12%

answer

  1. who may push against may anyone overwrite
  2. role thresholds versus no exceptions
  3. Free versus Ultimate
  4. the existing-tag check comes second

basics

~20 s

A 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

for a junior

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.

for a middle

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.

for a senior

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.

for a principal

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.