Tags and Releases
Tags mark specific commits as versions; Releases package them for download.
Syntax
git tag -a v1.0.0 -m "message"
git push origin v1.0.0A tag is a permanent label on a specific commit, most often a version number like v1.0.0. Unlike branches, tags do not move.
Creating tags
git tag v1.0.0— lightweight tag.git tag -a v1.0.0 -m "First release"— annotated tag with a message.git push origin v1.0.0— tags are not pushed by default.
Releases
On GitHub, a Release wraps a tag with release notes and downloadable assets (binaries, zip files). Users can then grab a specific version easily.
Example
git tag -a v1.0.0 -m "First stable release"
git push origin v1.0.0
# Create a GitHub Release from the tag
gh release create v1.0.0 --title "v1.0.0" --notes "Initial release"When to use it
- A maintainer creates a v1.3.0 release tag after merging the final PR, which triggers a GitHub Actions workflow to publish to npm.
- A developer uses lightweight tags to mark internal review checkpoints without publishing a formal release.
- An operations team downloads a specific release asset (a compiled binary) from the GitHub Releases page to deploy to production.
More examples
Create and push a semver tag
An annotated tag stores the tagger name, date, and message — suitable for a formal release point that GitHub can display.
# Create an annotated tag
git tag -a v1.3.0 -m "Release v1.3.0: add dark mode and fix Safari login"
# Push the tag to GitHub
git push origin v1.3.0Create a GitHub Release via CLI
Creates a release on GitHub from the tag and attaches a compiled binary as a downloadable asset.
gh release create v1.3.0 \
--title "v1.3.0 — Dark Mode & Safari Fix" \
--notes "### What's new\n- Dark mode toggle\n- Fixed login crash on Safari 17" \
dist/app-linux-amd64List all tags in the repository
Lists tags sorted by semantic version in descending order, showing the full release history at a glance.
git tag --sort=-version:refname
# v1.3.0
# v1.2.1
# v1.2.0
# v1.1.0
Discussion