Create a Git tag and publish it on GitHub

Create a tag locally with git tag, then push that specific tag to GitHub. For a release marker, an annotated tag records a tagger, date, and message. A GitHub Release is a separate object that adds release notes and downloadable assets to a tag.

Create and push an annotated tag

First identify the commit you intend to release. For example, inspect the current tip of the remote main branch:

git fetch origin
git log -1 --oneline origin/main
git tag -a v1.0.0 origin/main -m "Release v1.0.0"
git show v1.0.0
git push origin refs/tags/v1.0.0

Replace the version and target with your intended release. Tagging origin/main after inspection avoids an unnecessary checkout or merge into your working branch. To tag an older commit, use its verified commit ID instead of origin/main.

Choose a lightweight tag only when you want a simple reference without an annotation. This is an alternative command using a different name, not a second step for the same tag:

git tag checkpoint-1 origin/main

git push origin --tags pushes all local tags; use it only when every one is intended for that remote. Pushing a single explicit tag makes the publication scope clear.

Create a tag through a GitHub Release

Open the repository's Releases page and select Draft a new release. In Choose a tag, select an existing tag or enter a new name and choose Create new tag. For a new tag, select the intended target branch. Add the release title, notes, and any assets, then publish when the target is ready.

If you need a particular commit or a locally signed tag, create and push that tag first, then choose it in the release form. Creating a release does not require an annotated tag. See GitHub's release workflow.

Inspect or remove a tag

git tag --list
git show v1.0.0

For an incorrectly published tag that can still be removed under the repository's rules:

git push origin --delete refs/tags/v1.0.0
git tag -d v1.0.0

These delete the remote and local references separately. They do not clean up every other clone or remove an associated GitHub Release. Protected tags or immutable releases may prevent deletion. For a release others already consume, prefer a new version and document the correction rather than moving the existing tag.

Common questions

Does an annotated tag include a signature? An annotation and a signature are different. -a requests an annotation; use git tag -s with a configured signing key when you need a signed tag, and git tag -v to verify it. Signing configuration can also affect the default behavior. See git-tag.

How should tags be named? Follow the project's versioning policy. Names such as v1.2.3 and v2.0.0-rc.1 are common. Git does not impose semantic versioning, so keep the tag, changelog, and release notes consistent.

Why not overwrite a mistaken tag? Other clones or build systems may still hold the old reference. A new release version makes the correction explicit and avoids two different commits being described by the same published name.

References

• Git push
• Git fetch