1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
---
stage: Create
group: Source Code
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Tags **(FREE ALL)**
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:
- Using a [webhook](../../integrations/webhook_events.md#tag-events) to automate actions
like Slack notifications.
- Signaling a [repository mirror](../mirror/index.md) to update.
- Running a CI/CD pipeline with [`if: $CI_COMMIT_TAG`](../../../../ci/jobs/job_control.md#common-if-clauses-for-rules).
When you [create a release](../../releases/index.md),
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:
- The tag name. (**{tag}**)
- Optional. If the tag is [protected](../../protected_tags.md), a **protected** badge.
- The commit SHA (**{commit}**), linked to the commit's contents.
- The commit's title and creation date.
- Optional. A link to the release (**{rocket}**).
- 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**](../../releases/index.md#create-a-release) (**{pencil}**) 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.
1. Select **Code > Tags**.
## View tagged commits in the commits list
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18795) in GitLab 15.10.
1. On the left sidebar, select **Search or go to** and find your project.
1. Select **Code > Commits**.
1. Commits with a tag are labeled with a tag icon (**{tag}**) and the name of the tag.
This example shows a commit tagged `v1.26.0`:
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.
1. To create an annotated tag, run one of the versions of `git tag` from the command line:
```shell
# 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
```
1. 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.
1. Select **Code > Tags**.
1. Select **New tag**.
1. Provide a **Tag name**.
1. For **Create from**, select an existing branch name, tag, or commit SHA.
1. Optional. Add a **Message** to create an annotated tag, or leave blank to
create a lightweight tag.
1. Select **Create tag**.
## Prevent tag deletion **(PREMIUM ALL)**
To prevent users from removing a tag with `git push`, create a [push rule](../push_rules.md).
## Trigger pipelines from a tag
GitLab CI/CD provides a [`CI_COMMIT_TAG` variable](../../../../ci/variables/predefined_variables.md)
to identify tags. Use this variable in job rules and workflow rules to test if the pipeline
was triggered by a tag.
In your `.gitlab-ci.yml` file for the CI/CD pipeline configuration of your project,
you can trigger based on a new tag:
- At the job level, with the [`only` keyword](../../../../ci/yaml/index.md#only--except).
- At the pipeline level, with the [workflow rules keywords](../../../../ci/yaml/workflow.md).
## Related topics
- [Tagging (Git reference page)](https://git-scm.com/book/en/v2/Git-Basics-Tagging)
- [Protected tags](../../protected_tags.md)
- [Tags API](../../../../api/tags.md)
|
