Immutable container tags

Use immutable tags to prevent container tags from being updated or deleted in your project.

By default, users with the Developer role or higher can push and delete image tags in all project container repositories. With tag immutability rules, you can:

• Prevent the modification of critical image tags and mitigate the risk of malicious or accidental changes.
• Create up to 5 protection rules per project.
• Apply protection rules across all container repositories in your project.

A tag is immutable when at least one immutability protection rule matches the name of the tag. If multiple rules match, the most restrictive rule applies.

Immutable tag rules:

• Can only be created, not updated
• Cannot be deleted by cleanup policies.

Comparison with protected tags

While both protected tags and immutable tags maintain image integrity, they serve different purposes.

Protected tags restrict who can create, update, or delete certain tags based on roles. Tag immutability ensures that once a tag is created, no one can update or delete it.

The diagram below shows how protection rules are evaluated in the context of an image push:

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD
    accTitle: Evaluation of protected and immutable tag rules
    accDescr: Flow chart showing the evaluation process for protected and immutable tag rules during an image push.
    A[User attempts to push a tag] --> B{Protected tag check:<br/>Does user have required role<br/>to push this tag pattern?}
    B -- Yes --> C{Does the tag already exist?}
    B -- No --> D[Push denied:<br/>Protected tag - insufficient permissions]
    C -- Yes --> E{Immutable tag check:<br/>Does tag match an<br/>immutable rule pattern?}
    C -- No --> F[Tag is created successfully]
    E -- Yes --> G[Push denied:<br/>Tag is immutable]
    E -- No --> H[Tag is overwritten successfully]

Example scenarios

For a project with these rules:

• Protected tag rule: Pattern v.* requires at least the Maintainer role.
• Immutable tag rule: Pattern v\d+\.\d+\.\d+ protects semantic version tags.

Prerequisites

To use immutable container tags, make sure the container registry is available:

• In GitLab.com, the container registry is enabled by default.
• In GitLab Self-Managed, enable the metadata database.

Create an immutable rule

Prerequisites:

• You must have the Owner role.

To create an immutable rule:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > Packages and registries.
3. Expand Container registry.
4. Under Protected container tags, select Add protection rule.
5. In Protection type, select Immutable.
6. In Apply immutability rule to tags matching, enter a regex pattern using RE2 syntax. Patterns must not exceed 100 characters. For more information, see regex pattern examples.
7. Select Add rule.

The immutable rule is created and matching tags are protected.

Regex pattern examples

Example patterns you can use to protect container tags:

Delete an immutable rule

Prerequisites:

• You must have the Owner role.

To delete an immutable rule:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > Packages and registries.
3. Expand Container registry.
4. Under Protected container tags, next to the immutable rule you want to delete, select Delete ( ).
5. When prompted for confirmation, select Delete.

The immutable rule is deleted and matching tags are no longer protected.

Propagation delay

Rule changes rely on JWT tokens to propagate between services. As a result, changes to protection rules and user access roles might take effect only after current JWT tokens expire. The delay equals the configured token duration:

• Default: 5 minutes
• GitLab.com: 15 minutes

Most container registry clients (including Docker, the GitLab UI, and the API) request a new token for each operation, but custom clients might retain a token for its full validity period.

Image manifest deletions

The GitLab UI and API do not support direct image manifest deletions. Through direct container registry API calls, manifest deletions affect all associated tags.

To ensure tag protection, direct manifest deletion requests are only allowed when there are no immutable tag rules in the corresponding project.

This restriction applies regardless of whether the rule patterns match the container image tags.