Skip to content

Add GitHub tag badge to README

A GitHub tag badge displays the latest tag (often a release version) from your repository directly in your README. It’s a quick visual cue for users to see the current version without digging into the tags page.

How It Works

  • Use Shields.io to generate a dynamic badge.
  • Shields queries the GitHub API for your repo’s tags and renders a badge image that updates automatically when you push a new tag.

Prerequisites

  • Public repository — Shields.io can’t read tags from private repos unless you self‑host it.
  • At least one tag pushed to GitHub — ideally following Semantic Versioning (e.g., v1.0.0).
  • Correct repo name format — OWNER/REPO (no .git suffix).

Adding the Badge

Basic “Latest Tag” Badge

[![GitHub tag](https://img.shields.io/github/tag/OWNER/REPO)](https://github.com/OWNER/REPO/tags)

Latest Tag (Semantic Version Sorting)

[![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/OWNER/REPO?sort=semver)](https://github.com/OWNER/REPO/tags)

Replace: - OWNER → your GitHub username or org name
- REPO → your repository name

Common Issues & Fixes

Problem Cause Fix
Badge says “repo not found” .git suffix in URL or wrong owner/repo name Remove .git and use OWNER/REPO format
Badge shows “no tags” No tags in repo Create and push a tag: git tag v1.0.0 && git push origin v1.0.0
Badge doesn’t update Cached by Shields.io Append ?cacheSeconds=3600 to URL to control refresh
Private repo Shields can’t access it Make repo public or self‑host Shields

Example for grinntec/git-helper

[![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/grinntec/git-helper?sort=semver)](https://github.com/grinntec/git-helper/tags)

GitHub tag (latest SemVer)

Best Practices

  • Use SemVer tags (v1.2.3) for predictable sorting.
  • Link the badge to your tags or releases page for easy navigation.
  • Combine with other badges (build status, license, downloads) for a professional README header.