Live streamJoin us for "State of code review 2024" on July 18thRegister today

How to push tags to GitHub

Kenny DuMez
Kenny DuMez
Graphite software engineer


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:

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

Lightweight tag:

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:

git push origin <tag_name>

For example:

git push origin v1.0

To push all your local tags to the GitHub repository:

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:

name: Release Workflow
- '*'
runs-on: ubuntu-latest
- 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:

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.

Stay unblocked. Ship faster.
Experience the new developer workflow - create, review, and merge code continuously. Get started with one command.
Get started

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2