git tag: Usage, Options & Common CI Errors

git tag marks a specific commit, usually a release, with a permanent name.

Tags are how release pipelines pin versions. Remember that tags are not pushed by default.

What it does

git tag creates a lightweight or annotated tag pointing at a commit. Annotated tags (-a) store a tagger, date, and message; lightweight tags are just a name.

Common usage

Terminal

git tag                       # list tags
git tag v1.2.0                # lightweight tag on HEAD
git tag -a v1.2.0 -m "Release 1.2.0"
git push origin v1.2.0        # tags are NOT pushed by default
git tag -d v1.2.0             # delete locally

Options

Flag	What it does
-a / --annotate	Create an annotated tag
-m <msg>	Tag message (implies annotated)
-d / --delete	Delete a tag locally
-l / --list <pattern>	List tags matching a pattern
-f / --force	Move an existing tag

Common errors in CI

fatal: tag 'vX' already exists - re-tagging needs -f, and the remote tag also needs git push --force origin vX (or delete-then-push). Tags missing on the runner usually means a shallow clone or that git fetch --tags was not run; set fetch-depth: 0.

Related guides

git describe: Usage, Options & Common CI Errorsgit describe produces a readable name from the nearest tag, ideal for build versions. Reference for --tags, -… git push: Usage, Options & Common CI Errorsgit push uploads local commits to a remote. Reference for -u, --force-with-lease, and tags, plus the rejected… git fetch: Usage, Options & Common CI Errorsgit fetch downloads remote objects and refs without touching your working tree. Reference for --depth, --unsh… git show: Usage, Options & Common CI Errorsgit show displays a commit, tag, or object with its diff. Reference for --stat, --name-only, blob viewing, an…