Set up and use immutable tags in the container registry
By default, container image tags in the Bitbucket Packages container registry are mutable, which means a user with permission to push container images can overwrite an existing tag with a different image. By setting up immutable tags, you and your team can create stronger guarantees for release tags, production tags, versioned image tags, or all container image tags in the workspace.
はじめる前に
To use immutable tags for container images:
You must be a workspace admin to set up and use immutable tags or manage any custom immutable tag rules.
Your workspace must have access to Bitbucket Packages.
You must be using the Bitbucket Packages container registry. Immutable tag protection doesn’t apply to other package types, such as Apache Maven or npm.
Immutable tags and how they work
Immutable tags are designed so that workspace admins can ensure that certain container image tags continue to point to the same digest after they have been published. Immutable tags are also protected from deletion by non-workspace admins.
If a container image tag is immutable, either because all tags are protected or because it matches a custom rule:
The first push of that container image tag to the registry succeeds.
After the push succeeds, the container image tag becomes immutable.
Any later attempt to overwrite or update an immutable container image tag will be rejected.
Any later attempt to delete an immutable container image tag will be blocked, unless the user is a workspace admin.
Recommended container image tags to make immutable
This can be particularly useful for container image tags such as the following:
prodstaginglatest-releasev1.2.0release-2026-04
Setting up custom rules for immutable tags
From the workspace’s Container settings page, you can choose whether no tags, all tags, or only tags matching custom rules are protected. When you choose to protect only some tags, custom rules are evaluated against the container image tag name being pushed.
Rule format
Custom rules for container images use a Rule name and an RE2 pattern. The pattern uses RE2 regular expression syntax to match container image tag names. See this page for a comprehensive reference of the syntax.
When you add or edit a rule, use the built-in Pattern tester to check whether a sample container image tag matches your RE2 pattern before you save the rule.
Rule limits
When Some tags are protected is selected, you can create up to 7 custom rules per workspace.
Each rule pattern can contain up to 100 characters.
What happens when rules change
When Some tags are protected is selected, rules affect whether container image tags are protected based on the current rule configuration. If your workspace adds a rule that matches an existing container image tag, that tag can become protected by the new rule.
Because rules apply across the workspace, changes can affect container image tags in any image in that workspace, regardless of the repository the image is linked to.
Important: Before editing or removing a rule, check whether any container image publishing workflows depend on that rule for release safety or compliance controls.
Setting up immutable tags
You must be a workspace admin to configure immutable tag protection for the Bitbucket Packages container registry.
To set up immutable tags for container images:
Select the Settings cog icon in the upper-right corner of Bitbucket.
Select Workspace settings from the Settings dropdown.
On the left sidebar, select Packages, and then select Container.
Under Immutable tags, choose how you want to configure container image tags.
Select No tags are protected to allow all tags to be overwritten (updated) or deleted.
Select All tags are protected to make every tag in the workspace immutable after it is first pushed.
Select Some tags are protected to protect only tags that match custom rules. When you select this option, you will see a list of customs rules and the option to add a rule.
Once saved, the selected tag protection setting applies to container image tags pushed to the Bitbucket Packages container registry in that workspace.
Add, edit, or delete custom rules
Add a rule
If you choose Some tags are protected, you can add a custom rule or rules to define which container image tags are immutable.
Under Some tags are protected, select the Add rule button.
In the Rule name field, enter a descriptive name for the rule.
In the RE2 pattern field, enter a regular expression (regex) that matches the tags you want to protect, such as
^latest$.Optional: Use the Pattern tester to test any RE2 patterns. Enter a sample tag and select the Test button to verify your pattern matches as expected before saving.
Select Save to add the rule to the list of custom rules.
Once you’re done adding rules, select the Save button to save any updates or changes.
Tip for adding a rule
Always use the built-in Pattern tester before saving a rule. Enter tag names you expect to match to confirm the pattern behaves correctly. This avoids accidentally locking tags you didn’t intend to protect.
Edit a rule
Select the Settings cog icon in the upper-right corner of Bitbucket.
Select Workspace settings from the Settings dropdown.
Select Packages on the left sidebar, and then select Container.
Under Immutable tags, select Some tags are protected. Note: The default is No tags are protected.
Find the rule you want to update in the list of Custom rules.
Select … (the Action menu), and then select Edit.
In the Edit rule dialog, you can update the Rule name or RE2 pattern. Note: The fields are pre-filled with the rule’s current values.
Optional: Use the Pattern tester to check the updated pattern against a sample tag before saving.
Select the Save button to update the rule.
Select the Save button to apply your changes.
ルールの削除
To remove a custom rule for protected container image tags:
Select the Settings cog icon in the upper-right corner of Bitbucket.
Select Workspace settings from the Settings dropdown.
Select Packages on the left sidebar, and then select Container.
Under Immutable tags, select Some tags are protected.
Find the rule you want to delete in the list of Custom rules.
Select … (the Action menu), and then select Delete.
Confirm the deletion, then select Save.
この内容はお役に立ちましたか?