Git Tags and Releases Explained — Lightweight vs Annotated, Versioning Strategy and CI/CD Integration

#!/usr/bin/env bash
# ─────────────────────────────────────────────────────────
# Demonstrating lightweight vs annotated tags on a real repo
# Run this inside any existing Git repository
# ─────────────────────────────────────────────────────────

# 1. Create a LIGHTWEIGHT tag — just a pointer, zero metadata
#    Use this for local bookmarks only; don't push these
git tag v1.0.0-local

# 2. Inspect what a lightweight tag actually is under the hood
#    It points directly to a commit object — no wrapper
git cat-file -t v1.0.0-local
# Output: commit

# 3. Create an ANNOTATED tag — this is a full Git object
#    -a  = annotated
#    -m  = inline message (skips the editor prompt)
#    This is what you should use for every real release
git tag -a v1.0.0 -m "Release v1.0.0: initial public launch with user auth and dashboard"

# 4. Inspect what an annotated tag is under the hood
#    It's a dedicated 'tag' object, not a raw commit pointer
git cat-file -t v1.0.0
# Output: tag

# 5. Read the full metadata stored inside the annotated tag
git cat-file -p v1.0.0
# Output:
# object 4a3f8c2d1e9b7a6f5d4c3b2a1f9e8d7c6b5a4f3e
# type commit
# tag v1.0.0
# tagger Jane Doe <jane@thecompany.io> 1718000000 +0100
# 
# Release v1.0.0: initial public launch with user auth and dashboard

# 6. Show the tag alongside its annotation in the log
#    Annotated tags appear; the lightweight tag does NOT show here
git log --oneline --decorate
# Output:
# 4a3f8c2 (HEAD -> main, tag: v1.0.0) feat: add user authentication module
# b3e1d9f feat: scaffold dashboard layout
# 91cc047 chore: initial project setup

# 7. List ALL tags (both types) in the repository
git tag --list
# Output:
# v1.0.0
# v1.0.0-local

#!/usr/bin/env bash
# ─────────────────────────────────────────────────────────
# A realistic SemVer tagging workflow
# ─────────────────────────────────────────────────────────

# ── SCENARIO: we just merged a minor feature to main ──

# Step 1: Make sure we're on main and fully up to date
git checkout main
git pull origin main

# Step 2: Tag the current HEAD as a minor release
#    The message should read like a brief release note
git tag -a v1.1.0 -m "Release v1.1.0: add CSV export, improve pagination performance"

# Step 3: Push JUST the new tag to the remote
#    git push origin main does NOT push tags — you must do this explicitly
git push origin v1.1.0

# ── SCENARIO: pre-release tagging before a major launch ──

# Tag a release candidate — CI will deploy this to staging, not production
git tag -a v2.0.0-rc.1 -m "Release candidate 1 for v2.0.0: new billing engine"
git push origin v2.0.0-rc.1

# Once QA signs off, promote to the real release
git tag -a v2.0.0 -m "Release v2.0.0: new billing engine (replaces legacy Stripe integration)"
git push origin v2.0.0

# ── SCENARIO: hotfix on a past version ──

# Check out the tag you need to patch — NOT main
git checkout v1.1.0

# Create a dedicated hotfix branch from this exact commit
git checkout -b hotfix/fix-csv-null-pointer

# ... make your fix, commit it ...
git commit -am "fix: handle null values in CSV export row builder"

# Tag the hotfix from this branch
git tag -a v1.1.1 -m "Hotfix v1.1.1: fix null pointer crash in CSV export"
git push origin hotfix/fix-csv-null-pointer
git push origin v1.1.1

# List all tags sorted by version (not alphabetically)
git tag --list --sort=version:refname
# Output:
# v1.0.0
# v1.1.0
# v1.1.1
# v2.0.0-rc.1
# v2.0.0

#!/usr/bin/env bash
# ─────────────────────────────────────────────────────────
# Tag push, delete, and emergency re-tag operations
# ─────────────────────────────────────────────────────────

# ── PUSHING TAGS ──

# Push a single specific tag — preferred for release workflows
git push origin v1.2.0

# Push ALL local tags at once — useful when bootstrapping a new remote
# Warning: also pushes any messy lightweight bookmarks you forgot about
git push origin --tags

# Better: push all ANNOTATED tags only (skips lightweight ones)
git push origin --follow-tags

# ── VERIFYING A TAG EXISTS ON THE REMOTE ──

# List all tags the remote knows about
git ls-remote --tags origin
# Output (partial):
# 4a3f8c2d1e9b7a6f5d4c3b2a1f9e8d7c6b5a4f3e  refs/tags/v1.0.0
# 7b2e4419f3c1d5a8e2b6c9d0f1a4b7e8c2d3f5a6  refs/tags/v1.1.0
# a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0  refs/tags/v1.2.0

# ── DELETING A TAG ──

# Step 1: delete the tag locally
git tag --delete v1.2.0-bad-release
# Output: Deleted tag 'v1.2.0-bad-release' (was f8a9b0c)

# Step 2: delete the tag from the remote
#    The colon syntax means: "push nothing into refs/tags/v1.2.0-bad-release"
git push origin :refs/tags/v1.2.0-bad-release
# Output:
# To github.com:thecompany/billing-service.git
#  - [deleted]         v1.2.0-bad-release

# Modern equivalent — easier to remember:
git push origin --delete v1.2.0-bad-release

# ── MOVING A TAG (emergency correction only) ──

# You tagged the wrong commit — fix it IMMEDIATELY before others pull
# -f = force, moves the existing tag to HEAD (or any commit you specify)
git tag -f -a v1.2.0 -m "Release v1.2.0: correct commit this time"

# Force-push the corrected tag to the remote
#    --force is required because you're overwriting an existing ref
git push origin v1.2.0 --force
# Output:
# To github.com:thecompany/billing-service.git
#  + f8a9b0c...7b2e441 v1.2.0 -> v1.2.0 (forced update)

# ── FETCHING TAGS FROM REMOTE (for teammates) ──

# After a force-push, teammates must explicitly update their local tag
git fetch origin --tags --force
# Without --force, Git will refuse to update a tag that already exists locally

# ─────────────────────────────────────────────────────────
# GitHub Actions workflow that creates a Release and builds
# a Docker image only when an annotated version tag is pushed.
#
# File location: .github/workflows/release_pipeline.yml
# ─────────────────────────────────────────────────────────

name: Release Pipeline

on:
  push:
    # This workflow ONLY triggers when a tag matching v*.*.* is pushed
    # It will NOT run on regular branch pushes — tags are the gate
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'

jobs:
  run-tests:
    name: Run Test Suite Before Releasing
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository at the tagged commit
        uses: actions/checkout@v4

      - name: Set up Node.js runtime
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install project dependencies
        run: npm ci

      - name: Execute full test suite — release is blocked if any test fails
        run: npm test

  create-github-release:
    name: Publish GitHub Release with Auto-Generated Notes
    runs-on: ubuntu-latest
    needs: run-tests          # Only runs if tests passed
    permissions:
      contents: write         # Required to create a Release
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0      # Full history needed for changelog generation

      - name: Extract version number from the Git tag
        # GITHUB_REF is 'refs/tags/v1.2.0' — strip the prefix to get '1.2.0'
        id: extract_version
        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT

      - name: Create Release with auto-generated PR-based changelog
        uses: softprops/action-gh-release@v2
        with:
          # generate_release_notes pulls titles from merged PRs since last release
          generate_release_notes: true
          name: "Release v${{ steps.extract_version.outputs.VERSION }}"
          # Mark as a pre-release if the tag contains a hyphen (e.g. v2.0.0-rc.1)
          prerelease: ${{ contains(github.ref, '-') }}

  build-and-push-docker-image:
    name: Build Docker Image Tagged with Release Version
    runs-on: ubuntu-latest
    needs: create-github-release
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Extract version tag for Docker labelling
        id: extract_version
        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT

      - name: Log in to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          push: true
          # Image is tagged both with the specific version AND 'latest'
          # This lets consumers pin to a version OR always pull the newest
          tags: |
            ghcr.io/${{ github.repository }}:${{ steps.extract_version.outputs.VERSION }}
            ghcr.io/${{ github.repository }}:latest