Tags

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

In Git, a tag marks an important point in a repository’s history. Git supports two types of tags:

  • Lightweight tags point to specific commits, and contain no other information. Also known as soft tags. Create or remove them as needed.
  • Annotated tags contain metadata, can be signed for verification purposes, and can’t be changed.

The creation or deletion of a tag can be used as a trigger for automation, including:

When you create a release, GitLab also creates a tag to mark the release point. Many projects combine an annotated release tag with a stable branch. Consider setting deployment or release tags automatically.

In the GitLab UI, each tag displays:

Example of a single tag

  • The tag name. ()
  • Optional. If the tag is protected, a protected badge.
  • The commit SHA (), linked to the commit’s contents.
  • The commit’s title and creation date.
  • Optional. A link to the release ().
  • Optional. If a pipeline has been run, the current pipeline status.
  • Download links to the source code and artifacts linked to the tag.
  • A Create release () link.
  • A link to delete the tag.

View tags for a project

To view all existing tags for a project:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Code > Tags.

View tagged commits in the commits list

History
  1. On the left sidebar, select Search or go to and find your project.
  2. Select Code > Commits.

  3. Commits with a tag are labeled with a tag icon () and the name of the tag. This example shows a commit tagged v1.26.0:

    A tagged commit in the Commits view

To view the list of commits in this tag, select the tag name.

Create a tag

Tags can be created from the command line, or the GitLab UI.

From the command line

To create either a lightweight or annotated tag from the command line, and push it upstream:

  1. To create a lightweight tag, run the command git tag TAG_NAME, changing TAG_NAME to your desired tag name.

  2. To create an annotated tag, run one of the versions of git tag from the command line: 

    # In this short version, the annotated tag's name is "v1.0",
# and the message is "Version 1.0".
git tag -a v1.0 -m "Version 1.0"

# Use this version to write a longer tag message
# for annotated tag "v1.0" in your text editor.
git tag -a v1.0
  3. Push your tags upstream with git push origin --tags.

From the UI

To create a tag from the GitLab UI:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Code > Tags.
  3. Select New tag.
  4. Provide a Tag name.
  5. For Create from, select an existing branch name, tag, or commit SHA.
  6. Optional. Add a Message to create an annotated tag, or leave blank to create a lightweight tag.
  7. Select Create tag.

Name your tag

Git enforces tag name rules to help ensure tag names remain compatible with other tools. GitLab adds extra requirements for tag names, and provides benefits for well-structured tag names.

GitLab enforces these additional rules on all tags:

  • No spaces are allowed in tag names.
  • Tag names starting with 40 or 64 hexadecimal characters are prohibited, because they are similar to Git commit hashes.
  • Tag names cannot start with -, refs/heads/, refs/tags/, or refs/remotes/
  • Tag names are case-sensitive.

Prevent tag deletion

Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

To prevent users from removing a tag with git push, create a push rule.

Trigger pipelines from a tag

GitLab CI/CD provides a predefined variable, CI_COMMIT_TAG, to identify tags in your pipeline configurations. You can use this variable in job rules and workflow rules to test if a pipeline was triggered by a tag.

By default, if your CI/CD jobs don’t have specific rules in place, they are included in a tag pipeline for any newly created tag.

In your .gitlab-ci.yml file for the CI/CD pipeline configuration of your project, you can use the CI_COMMIT_TAG variable to control pipelines for new tags:

  • At the job level with rules:if.
  • At the pipeline level with the workflow keyword.