What are Git Tags and Why Use Them?

Have you ever encountered a situation where there were multiple conflicting versions of your git repo? Git tags are a way to avoid this by marking specific points in your project's history. This can make it easier to track changes, manage releases, and collaborate with other devs.

Types of Tags

There are two types of tags in Git: lightweight and annotated. Lightweight tags are exactly as they sound; a simplistic way to name your latest version of project -- you're pretty much just naming a commit.

Annotated tags, on the other hand, include an author's name and email, date of the tag, and a message. You can also sign your tags with a GPG key to verify their authenticity.

Creating Git Tags

To create a tag in Git, you can use the command line or use the GitHub GUI. Either way, you're selecting a commit to tag, naming the tag, and optionally adding a description.

To create a tag on the command line, make sure that you are pointed to the desired commit and run:

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

This will create an annotated tag named v1.0.0 with the message "Version 1.0.0". Your name and email will be used as the author of the tag, once you push it to a remote repository.

On GitHub, you can achieve the same result using the "Releases" tab, which can be found on the page of your repo:

1. After navigating to the "Relases" tab, click on "Draft a new release".
2. Select the commit you want to tag.
3. Name the tag and include a concise description.
4. Click "Publish release".

Integrating Tags in a CI/CD Pipeline (using GitHub Actions)

Tags can be used to trigger specific actions in a CI/CD pipeline. For example, you can set up your pipeline to automatically deploy your project to a specified environment whenever a new tag is created. This can help streamline your release process and ensure that your project is always up-to-date.

My preferred way to implement this functionality in my projects is to use GitHub Actions. You can create a workflow that listens for a new push to the repository, which triggers the creation of a new tag.

Example Workflow

Here's an example of a GitHub Actions workflow that creates a new tag and release whenever a push is made to the main branch:

name: Release Version

on:
  push:
    branches:
      - main

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Bump version and push tag
        id: tag_version
        uses: lyndipc/github-tag-action@v6.1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          default_bump: patch # major | minor | patch

      # Create a GitHub release
      - name: Create Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ steps.tag_version.outputs.new_tag }}
          release_name: Release ${{ steps.tag_version.outputs.new_tag }}
          body: ${{ steps.tag_version.outputs.changelog }}

Workflow Explanation

In this example, the workflow listens for a push to the main branch and triggers the release job. The job checks out the repository and analyzes previous commits to determine the type of bump to make (major, minor, or patch). Afterward, Node.js is setup and the github-tag-action action is used to bump the version and push a new tag. A GitHub release is created with the tag name and changelog for that repo.

This doesn't include the details of the deployment process, but you can add additional steps to deploy your project to a specific environment after the tag is created.

Types of Bumps

When creating a new tag, you can choose to bump the version in three ways: major, minor, or patch. This is a common practice and helps to easily identify the significance of the changes in the new version. For example, a major bump indicates that there are breaking changes in the new version, while a patch bump indicates that only bug fixes were made.

You can indicate the type of bump you want to make by setting the default_bump parameter in the Bump version and push tag step of the workflow. For example, to make a patch bump, you would set default_bump: patch.

Alternatively, you can specify the type of bump you want to make by including it in the tag name when creating a new tag. For example, to make a minor bump, you would name the tag v1.1.0.

Additional Commands

Inspecting Tags

To see a list of tags in your repository, you can run:

git tag

This will list all tags in alphabetical order. To see more information about a specific tag, you can run:

git show v1.0.0