Prevent container image overwrites with immutable tags in Bitbucket Packages

[#1]

We're excited to announce that immutable tags are now available for the Bitbucket Packages container registry. With immutable tags, workspace admins can set container image tags from being overwritten, moved, or modified after they're first pushed.

Tags are how your team refers to container images, but by default they're mutable: anyone with push access can point an existing tag at a different version of the image. For a tag like v1.2.0 or prod, that means the image running in production today might not be the one you tested and approved yesterday. Immutable tags remove that uncertainty. Once a tag is locked, it points to the same image every time, so your releases stay reproducible, your deployments stay predictable, and you have the audit trail you need to meet compliance requirements.

Benefits of immutable tags

• Improve reproducibility: A locked tag always points to the same image digest, so the image you tested is the image you deploy.

• Reduce deployment risk: Immutable production and release tags can't be silently overwritten.

• Support compliance: Immutable release tags help teams meet audit and compliance requirements.

How immutable tags work

Immutable tag is configured at the workspace level from the Container settings page. You'll choose from three options:

• No tags are protected: All tags stay mutable. This is the default.

• All tags are protected: Every tag becomes immutable after it's first pushed.

• Some tags are protected: Only tags matching custom rules become immutable.

When you choose Some tags are protected, you can create up to 7 custom rules per workspace. Each rule uses a rule name and an RE2 regular expression pattern of up to 100 characters, evaluated against the tag name being pushed. A built-in pattern tester lets you check a sample tag before you save. Here are a few examples:

Goal	Example pattern	What it matches
Protect a production tag	^prod$	Only the tag prod
Protect semantic version tags	^v\d+\.\d+\.\d+$	Tags like v1.0.0 or v2.14.3
Protect release tags	^release-.*$	Tags like release-2026-04
Protect staging and production tags	^(staging|prod)$	Only staging and prod

Once a protected tag is pushed for the first time, it's locked. Any later push to that tag is rejected with a clear error message, and deletion is blocked for everyone except workspace admins.

Getting started

You must be a workspace admin to configure immutable tag. To set it up:

1. Select Settings in the upper-right corner of Bitbucket, then Workspace settings.

2. Select Packages, then open Container settings.

3. Under Immutable tags, choose No tags, All tags, or Some tags are protected.

4. If you choose Some tags, add custom rules and use the pattern tester to verify them before saving.

We recommend using immutable tags for release, production, and versioned images, keeping your rules simple, and testing your tagging strategy against your pipelines before a broad rollout. For full setup details, check out our support documentation.

Share your feedback

We're focused on continuing to improve Bitbucket Packages, and your feedback directly informs what we build next. Immutable tags exist because teams like yours told us they needed stronger guarantees for their container images, and we want to keep that conversation going.

So please, share your feedback in the Bitbucket community. Let us know what's working, what you'd like to see next, and what would help you get even more value out of Bitbucket Packages. We're listening, and your input plays a key role in shaping where Bitbucket Packages goes from here.