How to push tags to GitHub

Kenny DuMez
Kenny DuMez
Graphite software engineer


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


Tags in Git serve as markers pointing to specific commits, generally used to mark release points (v1.0, v2.0, etc.). Pushing these tags to GitHub helps in keeping the versions of a project visible and accessible. This guide explains how to use Git to push tags to GitHub, as well as how to automate the tagging and pushing process using GitHub Actions.

A tag in Git is a snapshot of your repository at a particular point in time. Tags are mostly used for release management to mark a significant update or stable release of the software. Tags can be either lightweight (just a pointer to a specific commit) or annotated (stored as full objects in the Git database, containing the tagger name, email, and date, and have a tagging message).

Before you can push tags to GitHub, you need to create them locally.

You can create both annotated and lightweight tags:

Annotated tag:

Terminal
git tag -a v1.0 -m "Release version 1.0"

Lightweight tag:

Terminal
git tag v1.0-lite

Both of these commands create tags referencing the commit HEAD is currently pointing to. For more information on the HEAD reference see this in-depth guide on Git HEAD.

Once you have created your tags, you can push them to GitHub. To push a single tag:

Terminal
git push origin <tag_name>

For example:

Terminal
git push origin v1.0

To push all your local tags to the GitHub repository:

Terminal
git push origin --tags

This command transfers all of your tags to the remote repository, which is useful when you have multiple tags that need to be synchronized.

GitHub Actions can automate your workflow, including actions triggered by pushing tags. Here's a basic example of a GitHub Actions workflow that triggers on tag push:

Terminal
name: Release Workflow
on:
push:
tags:
- '*'
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Check out code
uses: actions/checkout@v2
- name: Build and Test
run: |
echo "Building the application..."
# Add commands to build/test your application

This workflow is triggered whenever any tag is pushed to the repository. It checks out the code and can be extended to build or test your application or deploy it.

  • Use semantic versioning for tags to make it clear how the project is evolving.
  • Prefer annotated tags for releases because they contain more information about the release context, making them more useful for historical purposes.
  • Regularly prune old or irrelevant tags to keep the tag list manageable and relevant.

If a tag already exists with the same name but points to a different commit, Git will not overwrite it by default. If you need to update a tag to a new commit, you must delete the old tag and recreate it:

Terminal
git tag -d <tag_name>
git push origin --delete <tag_name>
git tag <tag_name>
git push origin <tag_name>

For further reading see the official Git documentation.

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2