- Prerequisites
- Create a protection rule
- Regex pattern examples
- Delete a protection rule
- Propagation delay
- Image manifest deletions
Protected container tags
-
Introduced as an experiment in GitLab 17.9 with a flag named
container_registry_protected_tags
. Disabled by default.
Control who can push and delete container tags 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 protection rules, you can:
- Restrict pushing and deleting tags to specific user roles.
- Create up to 5 protection rules per project.
- Apply these rules across all container repositories in your project.
A tag is protected when at least one protection rule matches its name. If multiple rules match, the most restrictive rule applies.
Protected tags cannot be deleted by cleanup policies.
Prerequisites
Before you can use protected container tags:
- You must use the new container registry version:
- GitLab.com: Enabled by default
- GitLab Self-Managed: Enable the metadata database
Create a protection rule
Prerequisites:
- You must have at least the Maintainer role
To create a protection rule:
- On the left sidebar, select Search or go to and find your project.
- Select Settings > Packages and registries.
- Expand Container registry.
- Under Protected container tags, select Add protection rule.
- Complete the fields:
- Protect container tags matching: Enter a regex pattern using RE2 syntax. Patterns must not exceed 100 characters. See regex pattern examples.
- Minimum role allowed to push: Select Maintainer, Owner, or Administrator.
- Minimum role allowed to delete: Select Maintainer, Owner, or Administrator.
- Select Add rule.
The protection rule is created and matching tags are protected.
Regex pattern examples
Example patterns you can use to protect container tags:
Pattern | Description |
---|---|
.*
| Protects all tags |
^v.*
| Protects tags that start with “v” (like v1.0.0 , v2.1.0-rc1 )
|
\d+\.\d+\.\d+
| Protects semantic version tags (like 1.0.0 , 2.1.0 )
|
^latest$
| Protects the latest tag
|
.*-stable$
| Protects tags that end with “-stable” (like 1.0-stable , main-stable )
|
stable\|release
| Protects tags that contain “stable” or “release” (like 1.0-stable )
|
Delete a protection rule
Prerequisites:
- You must have at least the Maintainer role
To delete a protection rule:
- On the left sidebar, select Search or go to and find your project.
- Select Settings > Packages and registries.
- Expand Container registry.
- Under Protected container tags, next to the protection rule you want to delete, select Delete ().
- When prompted for confirmation, select Delete.
The protection 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:
- Tag protection is disabled
- The user has permission to delete any protected tags