Introduction

Git tags are how you mark important points in repository history, most commonly releases such as v1.2.0. Bitbucket displays tags, but the underlying operation is still plain Git. In practice, you usually create tags locally and push them to the Bitbucket remote.

Understand Lightweight and Annotated Tags

Git supports two main tag types:

• Lightweight tags are just references to a commit.
• Annotated tags store metadata such as tagger, date, and message.

For release management, annotated tags are the safer default because they preserve context.

Create a lightweight tag:

git tag v1.2.0

Create an annotated tag:

git tag -a v1.2.0 -m "Release 1.2.0"

Most teams should prefer the annotated form.

Tag the Correct Commit

Before tagging, confirm which commit you want to mark.

git log --oneline --decorate -5

If you want to tag the current HEAD, create the tag directly. If you want an older commit, pass the hash:

git tag -a v1.2.0 8f1c2ab -m "Release 1.2.0"

This matters because tags are immutable markers by convention. Moving a published tag later is possible, but it creates confusion.

Push the Tag to Bitbucket

Creating a tag locally is not enough. Push it to the Bitbucket remote:

git push origin v1.2.0

If you created several tags and want to push them all:

git push origin --tags

Pushing one explicit tag is usually safer than pushing every local tag blindly.

Verify the Tag Locally and Remotely

Check the tag metadata locally:

git show v1.2.0

You can also list tags:

git tag

Once pushed, Bitbucket should show the tag under repository tags or refs, depending on UI layout. Even if the UI is slow to update, the remote Git ref is the real source of truth.

Use Tags for Releases and Deployments

Tags are useful for:

• Release versions.
• Deployment markers.
• Milestone snapshots.
• Linking builds to source history.

For example, CI can build directly from a tag:

git checkout v1.2.0

That makes it easier to reproduce exactly what was released.

Delete or Move a Tag Carefully

If a wrong tag is created and not yet widely used, you can delete it locally and remotely.

Delete local tag:

git tag -d v1.2.0

Delete remote tag:

git push origin :refs/tags/v1.2.0

If the tag was already used by CI, deployments, or other developers, changing it can break traceability. It is often better to create a corrected new tag instead.

Tagging from Bitbucket UI

Some Bitbucket editions expose UI actions for creating tags. That can be convenient for small workflows, but the Git command-line approach is still the most explicit and portable. It also fits normal release scripts and automation better than a manual web action.

If your team uses automation, prefer tagging in Git and pushing to Bitbucket rather than relying on UI-only steps.

Best Practices for Tag Naming

Pick one convention and keep it stable. Common patterns:

• 'v1.2.0'
• 'release-2026-03-07'
• 'prod-2026-03-07-01'

Stable naming helps CI, release notes, and dashboards stay predictable.

Common Pitfalls

• Creating a tag locally and forgetting to push it to Bitbucket.
• Using lightweight tags for releases when annotated tags would be clearer.
• Tagging the wrong commit because history was not checked first.
• Reusing or moving published tags and breaking reproducibility.
• Pushing all local tags when only one new release tag should be published.

Summary

• Bitbucket tags are standard Git tags stored on the remote.
• Create tags locally with git tag, preferably using annotated tags for releases.
• Push tags explicitly with git push origin TAG_NAME.
• Verify the target commit before tagging because tags are meant to be stable markers.
• Treat published tags as immutable for clean release history.