Tags and releases: lightweight versus annotated tags and how they travel

What it is

The git-tag documentation distinguishes two kinds. A lightweight tag is simply a name for an object, usually a commit, stored as a reference. An annotated tag (created with -a, -s or -u) is a tag object of its own that contains creation date, tagger name and e-mail, a message and optionally a cryptographic signature. The documentation states that annotated tags are meant for release while lightweight tags are meant for private or temporary labels, and that some commands such as git describe ignore lightweight tags by default for this reason.

Tags are not part of a branch. git push sends branches; --tags pushes everything under refs/tags, and --follow-tags (or push.followTags) pushes only annotated tags that point at commits being pushed.

Why it matters

A release tag is the thing that build systems, changelog generators and git describe-based version strings key on. A lightweight tag carries no record of who cut the release or when, cannot be signed, and is invisible to git describe unless --tags is added, which produces version strings that differ between machines. A tag that is pushed late, or not at all, leaves CI building an untagged commit.

How to apply

• Create releases with git tag -a v2.3.0 -m "Release 2.3.0" or -s to sign; put the release notes summary in the message.
• Push explicitly: git push origin v2.3.0, or set push.followTags so annotated tags travel with the branch. Avoid --tags in scripts, because it also pushes every local experiment tag.
• Let CI trigger on tag pushes matching v* and derive the version from git describe --tags --dirty or from the tag alone.
• Treat a pushed tag as immutable. The documentation's discussion of re-tagging advises admitting the mistake and using a new name; it states that Git does not change tags behind users' backs, so clones that already fetched the tag keep the old target.
• Keep tag names in one scheme (v1.2.3, never mixed with 1.2.3 or release-1.2.3) so sorting and globbing work.

Pitfalls

Tags travel separately from branches, so a tag can exist in one clone and be absent from another until it is pushed or fetched explicitly. Signing tags without publishing the key gives verifiers nothing to check. A tag names an object that is usually, but not necessarily, a commit, which surprises tools that assume commits. Platform "releases" are metadata attached to a tag; check whether deleting one also removes the tag before relying on either.

Protecting release tags

A tag-triggered release makes tag creation a release permission, and on a fresh repository anyone with write access has it, independent of branch protection. Restrict the pattern (v*) with tag rulesets on GitHub or protected tags on GitLab so that only release maintainers can create or delete it, and have the release job verify that the tagged commit lies on the reviewed history before it publishes: git merge-base --is-ancestor "$GITHUB_SHA" origin/main || exit 1 (or the release branch). Sign the tag as well, so the verification described in the signing methodology on this wiki applies to releases, and publish the signing keys where the build can fetch them.