Step-by-Step Guide on How to Create a Tag in GitLab

Creating tags in GitLab is an essential practice for version control and project management. Tags allow developers to mark specific points in the history of a repository, making it easier to identify important commits, releases, or milestones. This step-by-step guide will walk you through the process of creating both lightweight and annotated tags using the command line and the GitLab UI, as well as best practices for naming and managing your tags.

Key Takeaways

  • Tags in GitLab help in marking specific points in the repository history for easy identification of important commits.
  • There are two main types of tags: lightweight and annotated, each serving different purposes.
  • You can create tags using both the command line and the GitLab UI, providing flexibility based on your workflow.
  • Following best practices like Semantic Versioning can make your tags more meaningful and easier to manage.
  • Automating tag creation using GitLab CI/CD or webhooks can streamline your development process.

Understanding GitLab Tags

What is a GitLab Tag?

A GitLab tag marks an important point in a repository’s history. Tags in GitLab are used to capture a specific state of the codebase, often for releases or significant milestones. Tags are immutable, meaning once created, they cannot be altered. This makes them reliable markers for referencing specific points in your project’s timeline.

Types of GitLab Tags

GitLab supports two types of tags:

  • Lightweight Tags: These are simple pointers to a specific commit. They contain no additional information and are also known as soft tags. Lightweight tags are easy to create and remove as needed.
  • Annotated Tags: These tags contain metadata, such as the tagger’s name, email, and date. Annotated tags can also include a message and can be signed for verification purposes. Unlike lightweight tags, annotated tags are more secure and provide more context.

In GitLab Premium, you can prevent users from removing a tag with a push rule, adding an extra layer of security to your tagging strategy.

Setting Up Your GitLab Environment

Prerequisites for Tag Creation

Before you start creating tags in GitLab, ensure you have the necessary prerequisites in place. You need to have Git installed on your system and a GitLab account with the appropriate permissions to create tags in your repository. Additionally, make sure your project is already set up in GitLab.

Configuring Git on Your System

To begin configuring Git on your system, follow these steps:

  1. Install Git: Download and install Git from the official website.
  2. Set up your user name and email in Git:
    git config --global "Your Name"
    git config --global ""
  3. Verify your Git configuration:
    git config --list

Properly configuring the environment with Ansible can streamline the setup process significantly.

Once Git is configured, you are ready to start creating tags in your GitLab repository.

Creating a Lightweight Tag via Command Line

Creating a lightweight tag in GitLab is a straightforward process that can be done directly from the command line. This section will guide you through the necessary steps to create and verify lightweight tags.

Command Syntax for Lightweight Tags

To create a lightweight tag, use the following command:

git tag <tagname>

Replace <tagname> with a descriptive name for your tag. For example:

git tag v1.0

Executing this command creates a lightweight tag identified as v1.0. Lightweight tags are created with the absence of the -a, -s, or -m options. Lightweight tags create a new tag checksum and store it in the .git/ directory of the project’s repo.

Verifying Tag Creation

After creating a tag, you can verify its creation by listing all tags in your repository. To do this, run the following command:

git tag

This will output a list of all tags in your repository. If your tag appears in the list, it has been successfully created.

For a more comprehensive guide on configuring GitLab Runner for efficient CI/CD pipelines, choose Linux runners with Docker executor, optimize with tags, cache, and resources. Secure runners for smooth operation.

Creating an Annotated Tag via Command Line

Creating an annotated tag in GitLab via the command line is a straightforward process that adds valuable metadata to your tags. This metadata can include a message, the tagger’s name, and the date, making it easier to track and understand the context of each tag.

Command Syntax for Annotated Tags

To create an annotated tag, you can use the following command syntax:

git tag -a TAG_NAME -m "Tag message"

Replace TAG_NAME with your desired tag name and "Tag message" with a brief description of the tag. For example:

git tag -a v1.0 -m "Version 1.0"

This command will create a new annotated tag identified as v1.0 with the message "Version 1.0". Annotated tags are stored as full objects in the Git database, which means they include additional information such as the tagger’s name, email, and the date.

Adding Messages to Tags

When creating an annotated tag, you have the option to add a more detailed message. This can be done by omitting the -m flag and allowing Git to open your default text editor:

git tag -a v1.0

This command will prompt you to enter a detailed message in your text editor. This is useful for providing more context or information about the tag. Once you save and close the editor, the tag will be created with the detailed message.

Pro Tip: Annotated tags are particularly useful for marking release points (e.g., v1.0, v2.0) in your project. They provide a clear and informative way to document significant changes or milestones.

Pushing Tags to Remote Repository

Using git push Command

By default, Git tags are not pushed to the remote repository when you execute git push. To push a specific tag, use the following command:

git push origin <tagname>

For example, to push a tag named v3.0, you would use:

git push origin v3.0

Alternatively, to export all local tags to the remote repository, you can run:

git push origin --tags

Verifying Remote Tags

After pushing tags to the remote repository, it’s important to verify that they have been successfully uploaded. You can do this by listing the tags from the remote repository:

git ls-remote --tags origin

This command will display all the tags that are present in the remote repository. Always ensure your tags are correctly pushed and listed to avoid any discrepancies in your project versions.

Pushing tags to a remote repository is a crucial step in sharing your project’s milestones and versions with your team. Make sure to follow best practices to maintain a clean and organized repository.

Creating Tags Using GitLab UI

Creating tags in GitLab through the UI is a straightforward process that allows you to mark specific points in your repository’s history without using the command line. This method is particularly useful for those who prefer a graphical interface or are new to GitLab.

Navigating to Your Project

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.

Steps to Create a Tag in UI

  1. Provide a Tag name.
  2. For Create from, select an existing branch name, tag, or commit SHA.
  3. Optional: Add a Message to create an annotated tag, or leave blank to create a lightweight tag.
  4. Select Create tag.

In the GitLab UI, each tag displays the tag name, the commit SHA linked to the commit’s contents, the commit’s title and creation date, and optional elements like a protected badge, a link to the release, and the current pipeline status if a pipeline has been run.

Best Practices for Naming Tags

When naming tags in GitLab, it’s essential to follow best practices to ensure clarity and consistency across your project. Here are some guidelines to help you name your tags effectively:

Semantic Versioning

Adopting a consistent naming convention like Semantic Versioning can greatly enhance the readability and organization of your tags. Semantic Versioning follows a MAJOR.MINOR.PATCH format (e.g., v1.0.1, v1.1.0, v2.0.1). This method helps in easily identifying the nature of changes in each release.

Examples of Good Tag Names

To make the most of Git tags, consider the following examples of well-structured tag names:

  • v1.0.0: Initial release
  • v1.1.0: Introduction of new features
  • v1.1.1: Bug fixes and minor improvements

Using clear and descriptive names for your tags makes it easy to identify their purpose at a glance. Additionally, prefer using annotated tags for important milestones or public releases, as they provide more context and metadata.

Keep your tags in sync by regularly pushing them to your remote repository. This ensures that your team members have access to the latest tags and can collaborate effectively.

Managing Tags in GitLab

Viewing Existing Tags

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.

Deleting Unwanted Tags

Protected tags can only be deleted by using GitLab either from the UI or API. These protections prevent you from accidentally deleting a tag through local Git commands or third-party Git clients.

To delete a tag:

  1. Navigate to your project.
  2. Go to Repository > Tags.
  3. Find the tag you want to delete and click the Delete button next to it.

Note: Deleting a tag is a permanent action and cannot be undone. Make sure you really want to delete the tag before proceeding.

Automating Tag Creation

developer working on a computer with GitLab interface, automation concept, coding environment

Using GitLab CI/CD

Automating tag creation can significantly streamline your development workflow. By leveraging GitLab CI/CD, you can set up pipelines that automatically create tags based on specific triggers. For instance, you can configure a pipeline to create a tag whenever a merge request is approved. This ensures that your tags are always up-to-date with the latest changes.

Automating with Webhooks

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

  • Using a webhook to automate actions like Slack notifications.
  • Signaling a repository mirror to update.
  • Running a CI/CD pipeline with if: $CI_COMMIT_TAG.

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.

Pro Tip: Automating tag creation can save you time and reduce the risk of human error. Make sure to explore the [guide on accessing GitLab API]( to set up CI/CD pipelines, automate workflow, monitor pipelines, extract data with GitLab API using Go, and store data in CSV files.

Troubleshooting Common Issues

Tag Not Showing Up

If your tag is not showing up, the first step is to verify that the tag was created successfully. Use the git tag command to list all tags in your local repository. If the tag is missing, you may need to recreate it. Ensure you have pushed the tag to the remote repository using git push origin <tagname>. Sometimes, network issues can cause the push to fail, so double-check your internet connection.

Tag Push Fails

When a tag push fails, it is often due to permission issues or conflicts with existing tags. Make sure you have the necessary permissions to push tags to the repository. You can check your permissions in the GitLab UI under the project settings. If there is a conflict with an existing tag, you may need to delete the old tag before pushing the new one. Use git push --delete origin <tagname> to remove the conflicting tag from the remote repository.

Troubleshoot failed pipelines with logs. Customize GitLab CI/CD for different environments using variables and configurations.

Advanced Tagging Techniques

Tagging Specific Commits

When working on a project, you might need to tag a specific commit that marks an important milestone or a significant change. To do this, use the following command:

git tag <tagname> <commit>

Replace <tagname> with your desired tag name and <commit> with the commit hash. This command will create a lightweight tag pointing to the specified commit.

Tagging Old Commits

Sometimes, you may need to tag an older commit to mark a previous version or deployment. To tag an old commit, first, find the commit hash using:

git log

Once you have the commit hash, use the same command as above to create the tag:

git tag <tagname> <commit>

Tagging old commits can be particularly useful for maintaining a clear history of your project’s deployments.

Regularly push tags to your remote repository to ensure that your team members have access to the latest tags and can collaborate effectively.


Creating tags in GitLab is a straightforward process that can be done either through the command line or the GitLab UI. By following the steps outlined in this guide, you can efficiently manage your project’s versions and releases. Whether you’re tagging a specific commit or marking a significant release, GitLab provides the tools you need to keep your repository organized and your workflow smooth. Remember, tags are not just labels; they can trigger automation, streamline your CI/CD pipelines, and enhance your overall development process. Happy tagging!

Frequently Asked Questions

What is a GitLab tag?

A GitLab tag is a reference to a specific point in your project’s history, often used to mark release points like v1.0 or v2.0.

How do I create a lightweight tag via the command line?

To create a lightweight tag, use the command: `git tag `. Replace `` with your desired tag name.

What is the difference between a lightweight tag and an annotated tag?

A lightweight tag is simply a name for a specific commit, while an annotated tag includes a message, the tagger’s name, and the date.

How can I push tags to a remote repository?

You can push tags to a remote repository using the command: `git push origin –tags`.

Can I create tags using the GitLab UI?

Yes, you can create tags using the GitLab UI by navigating to your project, selecting Code > Tags, and then selecting New tag.

What are some best practices for naming tags?

It is recommended to use Semantic Versioning for naming tags, such as v1.0.0, v2.1.0, etc.

How do I delete an unwanted tag in GitLab?

To delete a tag, navigate to your project’s Tags page in the GitLab UI, find the tag you want to delete, and select the delete option.

What should I do if my tag is not showing up?

Ensure that you have pushed your tags to the remote repository using `git push origin –tags`. If the problem persists, check your GitLab permissions and settings.

You may also like...