Keeping track of software releases is a complicated task, and Git helps manage it. Using Git’s tagging system, you can create versioned release numbers that point to specific commits, and use them in your CI/CD automation to publish releases.
Tagging Releases in Git
Git tags are a lot like Git branches. They’re labels that point to specific commits, and can be used to check out a repository at a specific point in time. However, unlike branches, they’re not meant to be updated and changed, and will always point to a specific version.
Tags are commonly used to apply version numbers to specific releases, usually using semantic versioning format (Major.Minor.Patch). This is very useful for keeping track of releases, especially when issues arise and deployments must be reverted to a previous tag that is confirmed to work.
Tags are also used to signal to CI/CD pipelines that a release should be published. Some repositories may wish to publish a “latest” release on every single commit, especially when just running testing for develop branches. Tags are often used so that release CI pipelines only run and deploy when specifically requested.
When you push to a remote like GitHub, your tags will show up under the Releases tab, which allows anyone to clone or download the repo from that tag.
You can checkout specific tags with the git checkout command, in the same way that checking out a branch works.
git checkout v1.0.0
Creating Tags
Creating a simple tag is very easy. You will need to checkout the commit or branch that you want to tag, and then run git tag with the name of the tag.
git checkout master git tag v1.0.0
However, it’s common practice to use annotated tags, which allow setting a description and store additional data about who created them and when, much like commits do.
git tag -a v1.0.0 -m "New Release Version - Summary"
You can also tag earlier commits without checking them out:
git tag -a v1.2 commit_id
Tags aren’t pushed to remotes like GitHub with Git’s default push command. You’ll need to run it with --tags, or push the tag name manually.
git push origin --tags
Deleting and Editing Tags
Tags can be deleted as well, but it’s important to consider that removing tags from remote servers can mess with other collaborators on your repository. However, since you’re not actually editing Git history, it’s mostly like deleting an old branch, which doesn’t touch the actual commits.
You can delete tags by name with the -d flag:
git tag -d v1.0.0
And remove them from the remote with:
git push origin --delete v1.0.0
To edit a tag, you can use the -f flag to force Git to overwrite an existing tag:
git tag -f v1.0.0
Creating Releases on GitHub
GitHub also supports tags, but expands on it with their own “Releases” system. Releases can be made from tags, but they can also be made from any specific commit, or with the current HEAD of any branch.
The primary purpose of publishing releases is to provide pre-built binaries for people to download, something that is very useful on GitHub but that tags themselves don’t provide. Users would still need to clone a specific tag and build from source otherwise.
The other purpose is documenting release notes, and GitHub Releases supports markdown as well. This provides a nice place for users to scroll through releases and see the big version changes over time.
Creating a release is pretty easy. From the sidebar of your repository, click “Releases,” and create a new one:
From this screen, you’re able to type up release notes with markdown, and drag-and-drop binary files for the release. GitHub will automatically provide a link to the source code at that tag for you.
You can also create releases automatically from tags using GitHub Actions. This saves you from uploading binaries each time, which is a nice piece of automation for your repo.
