GitHub Tags Explained: How to Mark Versions & Important Points in Your Project History

When a project contains hundreds or thousands of commits, finding the exact version of the code you need can become difficult.

For example:

Commit 1
Commit 2
Commit 3
...
Commit 150
Commit 151

Now imagine telling a user:

"Download the code from commit 151."

That's not very convenient.

Instead, developers can give important points in their project history meaningful names such as:

v1.0.0
v1.1.0
v1.2.0
v2.0.0

These names are called Git tags.

GitHub makes tags especially useful because they can be used to identify software versions and create GitHub Releases.

In this article, you'll learn what GitHub Tags are, why they are useful, how tags work, version tags, annotated tags, tag naming conventions, and how tags connect with GitHub Releases.

---

What is a GitHub Tag?

A Git tag is a named reference to a specific point in a repository's Git history.

For example:

Commit A
   ↓
Commit B
   ↓
Commit C ← v1.0.0
   ↓
Commit D
   ↓
Commit E

The tag:

v1.0.0

identifies Commit C.

This makes it easier to refer to that exact version of the project.

---

GitHub Tags in Simple Words

Think of a tag like a bookmark.

Imagine you're reading a book and place a bookmark on an important page.

Later, instead of searching through all the pages, you can immediately return to that location.

Git tags work similarly:

Project History
       ↓
Important Point
       ↓
Tag
       ↓
Easy to Find Later

---

Why Are Tags Useful?

Tags are commonly used to mark:

• Software releases

• Stable versions

• Important milestones

• Beta versions

• Release candidates

• Production versions

For example:

v1.0.0 → First stable release
v1.1.0 → New features
v1.1.1 → Bug fixes
v2.0.0 → Major update

---

Tags and GitHub Releases

Tags and releases are closely connected.

A common workflow is:

Code
 ↓
Commit
 ↓
Tag
 ↓
GitHub Release

For example:

v1.0.0
   ↓
GitHub Release
   ↓
Version 1.0.0

The tag identifies the code version, while the release provides user-facing information such as release notes and downloadable assets.

---

Tag vs Release

Don't confuse these two.

Tag	Release
Marks a point in Git history	Publishes a version
Git feature	GitHub feature built around Git tags
Usually lightweight	Includes release information
Can exist without a release	Commonly associated with a tag
Useful for version identification	Useful for distributing versions

A simple way to remember:

Tag = Which code?

Release = What are we publishing about that code?

---

Example

Suppose your project has:

100 commits

You decide that Commit 100 is your first stable version.

You create:

v1.0.0

Now you can easily identify that point:

Commit 100
    ↑
   v1.0.0

Later, you make 50 more commits.

Commit 100 ← v1.0.0
    ↓
Commit 101
    ↓
...
    ↓
Commit 150 ← v1.1.0

Now you have two clearly identified versions.

---

Common Tag Naming Convention

One of the most common conventions is:

vMAJOR.MINOR.PATCH

Examples:

v1.0.0
v1.1.0
v1.1.1
v2.0.0

The v is a convention, not a requirement.

You may also see:

1.0.0
1.1.0
2.0.0

The important thing is to use a consistent naming strategy.

---

Understanding MAJOR, MINOR and PATCH

A common versioning model is:

MAJOR.MINOR.PATCH

For example:

2.5.3

means:

2 → MAJOR
5 → MINOR
3 → PATCH

---

MAJOR Tag

A major version usually represents significant changes, particularly changes that may not be backward compatible.

Example:

v1.0.0
   ↓
Major Changes
   ↓
v2.0.0

---

MINOR Tag

A minor version generally represents new functionality that remains compatible with the existing API or behavior.

Example:

v1.2.0
   ↓
New Feature
   ↓
v1.3.0

---

PATCH Tag

A patch version generally represents bug fixes and smaller corrections.

Example:

v1.3.0
   ↓
Bug Fix
   ↓
v1.3.1

---

Version Tag Example

Imagine you created a web application.

Your versions might look like:

v1.0.0
→ Initial release

v1.1.0
→ Added dark mode

v1.1.1
→ Fixed dark mode bug

v1.2.0
→ Added user profiles

v2.0.0
→ Major architecture update

This creates a clear project history.

---

Lightweight Tags

Git supports lightweight tags.

A lightweight tag is essentially a simple reference pointing to a specific Git object, commonly a commit.

Conceptually:

Tag
 ↓
Commit

It is useful when you simply want to mark a point in the repository.

---

Annotated Tags

Git also supports annotated tags.

Annotated tags contain additional information such as:

• Tag name

• Tagger

• Date

• Message

Conceptually:

Annotated Tag
     ↓
Metadata
     ↓
Commit

Annotated tags are often preferred for official releases because they carry additional information.

---

Lightweight vs Annotated Tags

Feature	Lightweight	Annotated
Simple reference	Yes	Yes
Metadata	Minimal	Yes
Tag message	No	Yes
Useful for official releases	Less suitable	Often preferred
More descriptive	No	Yes

For important software releases, annotated tags are generally a better choice.

---

Creating a Tag on GitHub

You can create tags through GitHub's web interface in supported repository workflows.

When creating a release, GitHub can also create or use a tag associated with that release.

For example:

Release
 ↓
Choose tag
 ↓
v1.0.0
 ↓
Publish

The exact interface can change as GitHub updates its UI.

---

Creating Tags Locally

Developers can also create tags using Git locally and then push them to GitHub.

For example:

git tag v1.0.0

Then:

git push origin v1.0.0

Now the tag can appear in the GitHub repository.

For an annotated tag, Git provides a command such as:

git tag -a v1.0.0 -m "Version 1.0.0"

and then:

git push origin v1.0.0

This creates a tag with additional metadata.

---

Listing Tags

You can view tags in GitHub through the repository's tags/releases area.

Locally, Git also provides:

git tag

which lists available tags.

For example:

v1.0.0
v1.1.0
v1.1.1
v2.0.0

---

Checking a Specific Tag

You may want to inspect the version represented by a tag.

For example:

git show v1.0.0

This can show information associated with that tag and the referenced history.

---

Checking Out a Tag

You can use a tag to inspect the code at a particular version.

For example:

git checkout v1.0.0

Modern Git workflows may also use:

git switch --detach v1.0.0

This allows you to examine the project as it existed at that tagged version.

---

Why Would You Checkout an Old Tag?

Suppose your application worked correctly in:

v1.5.0

but a problem appeared in:

v2.0.0

You can inspect the code associated with v1.5.0.

This can help with:

• Debugging

• Comparing versions

• Reproducing old bugs

• Understanding changes

• Investigating regressions

---

Tags and Software Releases

Tags are especially important in software release workflows.

A typical process is:

Development
     ↓
Testing
     ↓
Final Commit
     ↓
Create Tag
     ↓
Create GitHub Release
     ↓
Publish Version

For example:

v2.1.0

can identify exactly which source code belongs to that release.

---

Tags for Open-Source Libraries

Suppose you've created a Java library:

StudentUtils

Users may depend on:

StudentUtils v1.2.0

Later you release:

StudentUtils v1.3.0

Then:

StudentUtils v2.0.0

Tags allow each version to remain identifiable.

---

Why Version Tags Matter for Libraries

Imagine a developer's application uses:

Library v1.4.0

The library later changes significantly.

If versions weren't clearly identified, developers could have difficulty determining which code they're using.

Tags make version history much easier to understand.

---

Pre-Release Tags

Tags can also identify testing versions.

Examples:

v2.0.0-alpha.1
v2.0.0-beta.1
v2.0.0-rc.1

These indicate versions that are not necessarily final stable releases.

A possible progression is:

v2.0.0-alpha.1
       ↓
v2.0.0-beta.1
       ↓
v2.0.0-rc.1
       ↓
v2.0.0

---

Tags for Milestones

Tags don't have to be used only for releases.

You can use them to mark important project milestones where appropriate.

For example:

v0.1.0
→ Prototype

v0.5.0
→ Major feature milestone

v1.0.0
→ First stable release

However, teams should establish a consistent tagging strategy.

---

Tags and Branches

Tags and branches are different.

Branch

A branch continues to move as new commits are added.

main
 ↓
Commit
 ↓
Commit
 ↓
Commit

Tag

A tag generally identifies a particular point.

v1.0.0
   ↓
Specific Commit

Think of it as:

Branch → Moving pointer

Tag → Named milestone

---

Branch vs Tag

Feature	Branch	Tag
Changes over time	Yes	Generally no
Used for development	Yes	No
Marks a specific version	Sometimes	Excellent
Used for releases	Indirectly	Commonly
Moves automatically	Yes	No

---

Tags and Commits

A tag points to a specific point in the Git history.

For example:

Commit A
   ↓
Commit B
   ↓
Commit C ← v1.0.0
   ↓
Commit D
   ↓
Commit E

The tag continues to identify Commit C even after newer commits are created.

---

Can a Tag Be Changed?

Technically, tags can be moved or recreated, but changing a published version tag is generally a bad practice.

Imagine users downloaded:

v1.0.0

If you later move v1.0.0 to a completely different commit, users may have different code under the same version number.

This creates confusion.

For released software, prefer creating a new version instead.

For example:

v1.0.0

should remain associated with the original release.

If something needs to change:

v1.0.1

can be created.

---

Why Immutable Release Versions Matter

Suppose:

v1.0.0

was released on January 1.

A user downloads it.

Later, you silently change what v1.0.0 points to.

Now:

User A → v1.0.0 → Commit A

User B → v1.0.0 → Commit B

That's a serious versioning problem.

Stable releases should therefore have predictable, trustworthy references.

---

Deleting Tags

Tags can be deleted if necessary.

But deleting a tag that users depend on can cause problems.

Before deleting a published version tag, consider:

• Is the release still being used?

• Do users depend on it?

• Are automation workflows using it?

• Is documentation referencing it?

For important releases, avoid unnecessary tag deletion or rewriting.

---

GitHub Tag Protection and Rules

GitHub provides repository rules and rulesets that can help control important Git references and workflows.

For example, an organization may want to restrict who can create or update release tags.

This is particularly useful for production software.

---

Tags and GitHub Actions

Tags can trigger automated workflows.

For example:

Create Tag
    ↓
GitHub Actions
    ↓
Run Tests
    ↓
Build Application
    ↓
Create Release

A workflow can be configured to run when specific tag events occur.

For example, a project might use:

v*

as a pattern for version tags.

This means tags such as:

v1.0.0
v1.1.0
v2.0.0

can be used to trigger release automation, depending on the workflow configuration.

---

Example: Automated Release

Suppose you're developing a desktop application.

You create:

v1.5.0

GitHub Actions could then:

Tag v1.5.0
      ↓
Build Windows Version
      ↓
Build Linux Version
      ↓
Run Tests
      ↓
Create Release
      ↓
Upload Assets

This can make software releases much faster and more reliable.

We'll cover this automation in detail later in the series.

---

Tag Naming Best Practices

Use a consistent naming convention.

Good examples:

v1.0.0
v1.1.0
v1.1.1
v2.0.0

Avoid inconsistent naming such as:

final
final-new
latest
release2
new-version

Meaningful version tags make your project easier to understand.

---

Good Tag Naming for Pre-Releases

Use clear names such as:

v2.0.0-alpha.1
v2.0.0-beta.1
v2.0.0-rc.1

This communicates the stage of development.

---

Common Beginner Mistakes

Creating Tags Randomly

Use a consistent versioning strategy.

---

Moving Published Tags

Avoid changing what a published version points to.

---

Confusing Tags With Branches

Remember:

Branch → Development line

Tag → Specific point

---

Using "Latest" as a Version

latest doesn't communicate exactly which version you're using.

Use explicit versions such as:

v1.4.2

---

Deleting Important Tags

Removing a tag can break references, documentation, or automation.

---

GitHub Tags for Your Portfolio

Tags can make personal projects look more professional.

Instead of having:

100 Commits

you can show:

v1.0.0
v1.1.0
v2.0.0

This demonstrates that you understand version management.

---

Example: Student Project

Suppose you create:

Student-Management-System

Your development history could look like:

Initial Code
    ↓
v0.1.0
    ↓
Added Database
    ↓
v0.5.0
    ↓
Added Authentication
    ↓
v1.0.0
    ↓
Bug Fixes
    ↓
v1.0.1

This is a much clearer project history than simply having hundreds of unnamed commits.

---

GitHub Tags vs GitHub Releases

Here's the simplest comparison:

Tag
 ↓
Marks the exact code version

Release
 ↓
Publishes that version to users

For example:

v1.0.0 Tag
     ↓
GitHub Release
     ↓
Release Notes
     ↓
Downloadable Files

---

Frequently Asked Questions

What is a GitHub Tag?

A Git tag is a named reference to a specific point in a Git repository's history.

Are tags only used for releases?

No. They can also mark important milestones or other points in project history.

What is the difference between a tag and a branch?

A branch moves forward as development continues. A tag identifies a particular point.

Can I create tags from GitHub?

Yes. GitHub provides web workflows for creating tags, particularly when creating releases.

Can I create tags using Git?

Yes.

For example:

git tag v1.0.0

What is an annotated tag?

An annotated tag stores additional metadata such as the tagger, date, and message.

Should release tags be changed?

Generally, no. Published release tags should remain stable.

Can tags trigger GitHub Actions?

Yes. Workflows can be configured to run in response to tag-related events.

---

GitHub Tag Workflow

A professional versioning workflow can look like:

Develop
   ↓
Test
   ↓
Fix Bugs
   ↓
Stable Commit
   ↓
Create Version Tag
   ↓
Create GitHub Release
   ↓
Publish
   ↓
Users Download Version

---

Summary

GitHub Tags provide a simple way to identify important points in your project's history.

They're commonly used for:

• Software versions

• Releases

• Stable milestones

• Beta versions

• Release candidates

• Production versions

The most important concept is:

Commit
  ↓
Tag
  ↓
Specific Version
  ↓
GitHub Release

When used with consistent version numbering, tags make your project's history easier to understand and your software releases easier to manage.