Skip to main content

Git Tags and Releases

Now that you've mastered Git fundamentals and GitHub workflows, let's explore how to mark important milestones in your project's history. Git tags provide permanent markers for specific commits, while GitHub releases package these tagged commits with downloadable assets and release notes.

In this lesson you'll learn how to:

  • Create lightweight and annotated tags in Git
  • Push tags to remote repositories
  • Create GitHub releases from tags
  • Manage and delete tags when needed

Understanding Git Tags​

Git tags are references that point to specific commits in your repository's history. Unlike branches, tags are immutable—once created, they don't move as new commits are added. This makes them perfect for marking release points like v1.0.0, v2.1.3, or production-ready.

There are two main types of Git tags:

  • Lightweight tags: Simple pointers to specific commits
  • Annotated tags: Full Git objects with metadata (author, date, message)

Creating Local Tags​

Lightweight Tags​

Lightweight tags are the simplest way to mark a commit. They're essentially bookmarks that don't store additional information.

Creating a lightweight tag
git tag v1.0.0-lite

This creates a tag pointing to your current HEAD commit.

Annotated Tags​

Annotated tags are more comprehensive and recommended for releases because they include metadata and can be signed for verification.

Creating an annotated tag
git tag -a v1.0.0 -m "Initial production release"

The -a flag creates an annotated tag, and -m lets you add a message describing the release.

tip

Always use annotated tags for important milestones. They store creation date, tagger information, and a message, making them much more useful for tracking releases.

Tagging Specific Commits​

You can tag any commit in your history, not just the current one:

Tagging a previous commit
git tag -a v0.9.0 abc123f -m "Beta release"

Replace abc123f with an actual commit hash from your repository.

Listing and Viewing Tags​

View all tags in your repository:

Listing all tags
git tag

For a more detailed view with tag messages:

Detailed tag listing
git tag -n

View information about a specific tag:

Inspecting a tag
git show v1.0.0

Pushing Tags to Remote​

By default, tags aren't pushed to remote repositories when you use git push. You need to explicitly push them.

Pushing a single tag
git push origin v1.0.0

Push all tags at once:

Pushing all tags
git push origin --tags
warning

Be careful with --tags as it pushes all your local tags. In collaborative environments, coordinate with your team before pushing tags to avoid conflicts.

Creating GitHub Releases​

While Git tags mark commits locally and remotely, GitHub Releases provide a user-friendly interface with release notes, binary assets, and a dedicated download page.

Creating Releases from the GitHub Interface​

  1. Navigate to your repository on GitHub
  2. Click "Releases" in the right sidebar
  3. Click "Draft a new release"
  4. Select an existing tag or create a new one
  5. Add a title and detailed release notes
  6. Attach any binary files (compiled executables, documentation, etc.)
  7. Mark as pre-release if appropriate
  8. Publish the release

Creating Releases via Git Tags​

You can also create releases by pushing annotated tags:

Creating a release candidate
git tag -a v1.1.0-rc1 -m "Release candidate 1 for version 1.1.0"
git push origin v1.1.0-rc1

Then complete the release through GitHub's web interface.

Managing and Deleting Tags​

Deleting Local Tags​

Removing a local tag
git tag -d v1.0.0-lite

Deleting Remote Tags​

Removing a remote tag
git push origin --delete v1.0.0-lite
note

Deleting tags is generally safe for lightweight tags but use caution with annotated tags that might be referenced in releases or documentation.

Practical Example: Tagging a Release​

Let's walk through a complete release workflow:

Complete release tagging workflow
# Make sure you're on the main branch and up to date
git checkout main
git pull origin main

# Create an annotated tag for the new release
git tag -a v1.2.0 -m "Version 1.2.0: Added user authentication"

# Push the tag to GitHub
git push origin v1.2.0

# Now create the release on GitHub with detailed notes

Common Pitfalls​

  • Forgetting to push tags: Tags stay local unless explicitly pushed
  • Using lightweight tags for releases: They lack metadata and can't be verified
  • Tag naming conflicts: Avoid names that could conflict with branch names
  • Deleting tags used in releases: This can break references in documentation or CI/CD pipelines
  • Not signing important tags: For production releases, consider using signed tags for verification

Summary​

Git tags provide permanent markers for important commits, with annotated tags being the preferred choice for releases due to their metadata. GitHub Releases build on tags by adding release notes, binary assets, and a polished presentation. Remember to push your tags to remote repositories and use the GitHub interface to create comprehensive releases that users can easily access and understand.

Quiz​

Git Tags and Releases – Quick Check

What is the key difference between lightweight and annotated tags?

Question 1/5