2020-05-27 03:08:26 +00:00
---
stage: Plan
group: Project Management
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---
2016-06-21 16:54:30 +00:00
# Labels
2020-04-23 21:09:31 +00:00
As your count of issues, merge requests, and epics grows in GitLab, it's more and more challenging
to keep track of those items. Especially as your organization grows from just a few people to
hundreds or thousands. This is where labels come in. They help you organize and tag your work
so you can track and find the work items you're interested in.
Labels are a key part of [issue boards ](issue_board.md ). With labels you can:
- Categorize epics, issues, and merge requests using colors and descriptive titles like
`bug` , `feature request` , or `docs` .
- Dynamically filter and manage epics, issues, and merge requests.
- [Search lists of issues, merge requests, and epics ](../search/index.md#issues-and-merge-requests ),
as well as [issue boards ](../search/index.md#issue-boards ).
2016-06-21 16:54:30 +00:00
2018-02-07 15:17:00 +00:00
## Project labels and group labels
2020-01-31 06:08:59 +00:00
There are two types of labels in GitLab:
2018-02-07 15:17:00 +00:00
2019-11-22 00:06:08 +00:00
- **Project labels** can be assigned to issues and merge requests in that project only.
2020-01-31 06:08:59 +00:00
- **Group labels** can be assigned to issues and merge requests in any project in
the selected group or its subgroups.
- They can also be assigned to epics in the selected group or its subgroups.**(ULTIMATE)**
2019-05-05 15:37:18 +00:00
2020-01-31 06:08:59 +00:00
## Assign and unassign labels
2019-05-05 15:37:18 +00:00
2020-10-13 15:08:53 +00:00
> Unassigning labels with the **X** button [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216881) in GitLab 13.5.
Every issue, merge request, and epic can be assigned any number of labels. The labels are
2020-01-31 06:08:59 +00:00
managed in the right sidebar, where you can assign or unassign labels as needed.
2019-05-05 15:37:18 +00:00
2020-10-13 15:08:53 +00:00
To assign or unassign a label:
1. In the **Labels** section of the sidebar, click **Edit** .
1. In the **Assign labels** list, search for labels by typing their names.
You can search repeatedly to add more labels.
The selected labels are marked with a checkmark.
1. Click the labels you want to assign or unassign.
1. To apply your changes to labels, click **X** next to **Assign labels** or anywhere outside the
label section.
2019-05-05 15:37:18 +00:00
2020-10-13 15:08:53 +00:00
Alternatively, to unassign a label, click the **X** on the label you want to unassign.
2016-06-21 16:54:30 +00:00
2020-10-13 15:08:53 +00:00
You can also assign a label with the `/label` [quick action ](quick_actions.md ),
remove labels with `/unlabel` , and reassign labels (remove all and assign new ones) with `/relabel` .
2016-06-21 16:54:30 +00:00
2020-01-31 06:08:59 +00:00
## Label management
2016-06-21 16:54:30 +00:00
2020-01-31 06:08:59 +00:00
Users with a [permission level ](../permissions.md ) of Reporter or higher are able to create
and edit labels.
2016-06-21 16:54:30 +00:00
2020-01-31 06:08:59 +00:00
### Project labels
2016-08-09 13:12:27 +00:00
2020-10-14 15:08:42 +00:00
To view the project labels list, navigate to the project and click **Issues > Labels** .
2020-01-31 06:08:59 +00:00
The list includes all labels that are defined at the project level, as well as all
2020-10-13 06:09:09 +00:00
labels inherited from the immediate parent group.
For each label, you can see the project or group path from where it was created.
You can filter the list by entering a search query at the top and clicking search (**{search}**).
2016-08-09 13:12:27 +00:00
2020-01-31 06:08:59 +00:00
To create a new project label:
2016-08-09 13:12:27 +00:00
2020-01-31 06:08:59 +00:00
1. Navigate to **Issues > Labels** in the project.
1. Click the **New label** button.
- Enter the title.
- (Optional) Enter a description.
- (Optional) Select a background color by clicking on the available colors, or input
a hex color value for a specific color.
1. Click **Create label** to create the label.
2016-06-21 16:54:30 +00:00
2020-01-31 06:08:59 +00:00
You can also create a new project label from within an issue or merge request. In the
label section of the right sidebar of an issue or a merge request:
2016-08-09 13:12:27 +00:00
2020-01-31 06:08:59 +00:00
1. Click **Edit** .
1. Click **Create project label** .
- Fill in the name field. Note that you can't specify a description if creating a label
this way. You can add a description later by editing the label (see below).
- (Optional) Select a color by clicking on the available colors, or input a hex
color value for a specific color.
1. Click **Create** .
2016-08-09 13:12:27 +00:00
2020-01-31 06:08:59 +00:00
Once created, you can edit a label by clicking the pencil (**{pencil}**), or delete
a label by clicking the three dots (**{ellipsis_v}**) next to the **Subscribe** button
and selecting **Delete** .
2019-07-31 23:55:37 +00:00
2020-08-09 21:10:01 +00:00
CAUTION: **Caution:**
2020-10-14 15:08:42 +00:00
If you delete a label, it is permanently deleted. All references to the label are removed from the system and you cannot undo the deletion.
2020-08-09 21:10:01 +00:00
2020-01-31 06:08:59 +00:00
#### Promote a project label to a group label
2019-08-07 04:03:04 +00:00
2020-01-31 06:08:59 +00:00
If you previously created a project label and now want to make it available for other
2020-03-30 18:08:07 +00:00
projects within the same group, you can promote it to a group label.
2020-10-14 15:08:42 +00:00
If other projects in the same group have a label with the same title, they are all
merged with the new group label. If a group label with the same title exists, it is
also merged.
2020-03-30 18:08:07 +00:00
All issues, merge requests, issue board lists, issue board filters, and label subscriptions
2020-10-14 15:08:42 +00:00
with the old labels are assigned to the new group label.
2019-05-05 15:37:18 +00:00
2020-07-16 06:09:33 +00:00
CAUTION: **Caution:**
2020-01-31 06:08:59 +00:00
Promoting a label is a permanent action, and cannot be reversed.
2016-06-21 16:54:30 +00:00
2020-01-31 06:08:59 +00:00
To promote a project label to a group label:
2016-06-21 16:54:30 +00:00
2020-01-31 06:08:59 +00:00
1. Navigate to **Issues > Labels** in the project.
1. Click on the three dots (**{ellipsis_v}**) next to the **Subscribe** button and
select **Promote to group label** .
2016-06-21 16:54:30 +00:00
2020-01-31 06:08:59 +00:00
### Group labels
2016-06-21 16:54:30 +00:00
2020-10-14 15:08:42 +00:00
To view the group labels list, navigate to the group and click **Issues > Labels** .
2020-01-31 06:08:59 +00:00
The list includes all labels that are defined at the group level only. It does not
list any labels that are defined in projects. You can filter the list by entering
a search query at the top and clicking search (**{search}**).
2016-06-21 16:54:30 +00:00
2020-01-31 06:08:59 +00:00
To create a **group label** , navigate to **Issues > Labels** in the group and
follow the same process as [creating a project label ](#project-labels ).
2016-06-22 11:50:02 +00:00
2020-01-31 06:08:59 +00:00
#### Create group labels from epics **(ULTIMATE)**
2016-06-22 11:50:02 +00:00
2020-10-14 15:08:42 +00:00
You can create group labels from the epic sidebar. The labels you create
2020-01-31 06:08:59 +00:00
belong to the immediate group to which the epic belongs. The process is the same as
creating a [project label from an issue or merge request ](#project-labels ).
2016-06-22 11:50:02 +00:00
2020-01-31 06:08:59 +00:00
### Generate default labels
2016-06-22 11:50:02 +00:00
2020-01-31 06:08:59 +00:00
If a project or group has no labels, you can generate a default set of project or group
2020-10-14 15:08:42 +00:00
labels from the label list page. The page shows a **Generate a default set of labels**
button if the list is empty. Select the button to add the following default labels
2020-01-31 06:08:59 +00:00
to the project:
2019-07-31 23:55:37 +00:00
2020-01-31 06:08:59 +00:00
- `bug`
- `confirmed`
- `critical`
- `discussion`
- `documentation`
- `enhancement`
- `suggestion`
- `support`
2016-06-22 11:50:02 +00:00
2020-01-31 06:08:59 +00:00
## Scoped labels **(PREMIUM)**
2018-08-07 15:28:41 +00:00
2020-05-22 03:08:28 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9175) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10.
2018-08-07 15:28:41 +00:00
2020-01-31 06:08:59 +00:00
Scoped labels allow teams to use the label feature to annotate issues, merge requests
and epics with mutually exclusive labels. This can enable more complicated workflows
by preventing certain labels from being used together.
2019-07-31 23:55:37 +00:00
2020-01-31 06:08:59 +00:00
A label is scoped when it uses a special double-colon (`::`) syntax in the label’ s
title, for example:
2019-07-31 23:55:37 +00:00
2020-10-14 00:08:48 +00:00
![Scoped labels ](img/labels_key_value_v13_5.png )
2018-08-07 15:28:41 +00:00
2020-01-31 06:08:59 +00:00
An issue, merge request or epic cannot have two scoped labels, of the form `key::value` ,
2020-10-14 15:08:42 +00:00
with the same `key` . Adding a new label with the same `key` , but a different `value`
causes the previous `key` label to be replaced with the new label.
2016-06-22 11:50:02 +00:00
2020-10-14 15:08:42 +00:00
For example:
2016-06-22 11:50:02 +00:00
2020-01-31 06:08:59 +00:00
1. An issue is identified as being low priority, and a `priority::low` project
label is added to it.
1. After more review the issue priority is increased, and a `priority::high` label is
added.
1. GitLab automatically removes the `priority::low` label, as an issue should not
have two priority labels at the same time.
2016-06-22 11:50:02 +00:00
2020-01-31 06:08:59 +00:00
### Workflows with scoped labels
2016-06-22 11:50:02 +00:00
2020-01-31 06:08:59 +00:00
Suppose you wanted a custom field in issues to track the operating system platform
that your features target, where each issue should only target one platform. You
would then create three labels `platform::iOS` , `platform::Android` , `platform::Linux` .
Applying any one of these labels on a given issue would automatically remove any other
existing label that starts with `platform::` .
2019-05-05 15:37:18 +00:00
2020-01-31 06:08:59 +00:00
The same pattern could be applied to represent the workflow states of your teams.
Suppose you have the labels `workflow::development` , `workflow::review` , and
`workflow::deployed` . If an issue already has the label `workflow::development`
applied, and a developer wanted to advance the issue to `workflow::review` , they
would simply apply that label, and the `workflow::development` label would
automatically be removed. This behavior already exists when you move issues
2020-04-22 18:09:52 +00:00
across label lists in an [issue board ](issue_board.md#create-workflows ), but
2020-01-31 06:08:59 +00:00
now, team members who may not be working in an issue board directly would still
be able to advance workflow states consistently in issues themselves.
2016-06-22 11:50:02 +00:00
2020-01-31 06:08:59 +00:00
This functionality is demonstrated in a video regarding
[using scoped labels for custom fields and workflows ](https://www.youtube.com/watch?v=4BCBby6du3c ).
2016-06-22 11:50:02 +00:00
2020-01-31 06:08:59 +00:00
### Scoped labels with nested scopes
2019-07-31 23:55:37 +00:00
2020-01-31 06:08:59 +00:00
You can create a label with a nested scope by using multiple double colons `::` when creating
2020-10-14 15:08:42 +00:00
it. In this case, everything before the last `::` is the scope.
2019-07-31 23:55:37 +00:00
2020-01-31 06:08:59 +00:00
For example, `workflow::backend::review` and `workflow::backend::development` are valid
scoped labels, but they **can't** exist on the same issue at the same time, as they
both share the same scope, `workflow::backend` .
2019-07-31 23:55:37 +00:00
2020-03-26 03:07:43 +00:00
Additionally, `workflow::backend::review` and `workflow::frontend::review` are valid
2020-01-31 06:08:59 +00:00
scoped labels, and they **can** exist on the same issue at the same time, as they
both have different scopes, `workflow::frontend` and `workflow::backend` .
2016-06-21 16:54:30 +00:00
2018-02-07 15:17:00 +00:00
## Subscribing to labels
2016-06-21 16:54:30 +00:00
2020-01-31 06:08:59 +00:00
From the project label list page and the group label list page, you can click **Subscribe**
to the right of any label to enable [notifications ](../profile/notifications.md ) for that
2020-10-14 15:08:42 +00:00
label. You are notified whenever the label is assigned to an epic,
2020-01-31 06:08:59 +00:00
issue, or merge request.
If you are subscribing to a group label from within a project, you can select to subscribe
to label notifications for the project only, or the whole group.
2016-06-21 16:54:30 +00:00
2020-10-14 00:08:48 +00:00
![Labels subscriptions ](img/labels_subscriptions_v13_5.png )
2016-06-21 16:54:30 +00:00
2018-02-07 15:17:00 +00:00
## Label priority
2016-06-21 16:54:30 +00:00
2020-05-22 03:08:28 +00:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/14189) in GitLab 8.9.
> - Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/14523) considers changing this.
2016-06-21 16:54:30 +00:00
2020-01-31 06:08:59 +00:00
Labels can have relative priorities, which are used in the **Label priority** and
**Priority** sort orders of the epic, issue, and merge request list pages. Prioritization
for both group and project labels happens at the project level, and cannot be done
from the group label list.
2019-07-31 23:55:37 +00:00
From the project label list page, star a label to indicate that it has a priority.
2020-10-14 00:08:48 +00:00
![Labels prioritized ](img/labels_prioritized_v13_5.png )
2019-07-31 23:55:37 +00:00
2020-01-31 06:08:59 +00:00
Drag starred labels up and down the list to change their priority, where higher in the list
means higher priority.
2016-06-21 16:54:30 +00:00
2019-07-31 23:55:37 +00:00
![Drag to change label priority ](img/labels_drag_priority_v12_1.gif )
2016-06-21 16:54:30 +00:00
2020-03-05 09:08:31 +00:00
On the epic, merge request, and issue list pages (for both groups and projects) you
2020-01-31 06:08:59 +00:00
can sort by `Label priority` or `Priority` .
2016-06-21 16:54:30 +00:00
2020-01-31 06:08:59 +00:00
If you sort by `Label priority` , GitLab uses this sort comparison order:
2016-06-21 16:54:30 +00:00
2020-01-31 06:08:59 +00:00
1. Items with a higher priority label.
1. Items without a prioritized label.
2016-06-21 16:54:30 +00:00
2020-01-31 06:08:59 +00:00
Ties are broken arbitrarily. Note that only the highest prioritized label is checked,
2020-05-22 03:08:28 +00:00
and labels with a lower priority are ignored. See this [related issue ](https://gitlab.com/gitlab-org/gitlab/-/issues/14523 )
2020-01-31 06:08:59 +00:00
for more information.
2016-06-21 16:54:30 +00:00
2018-02-07 15:17:00 +00:00
![Labels sort label priority ](img/labels_sort_label_priority.png )
2016-06-21 16:54:30 +00:00
2020-01-31 06:08:59 +00:00
If you sort by `Priority` , GitLab uses this sort comparison order:
2016-06-21 16:54:30 +00:00
2020-01-31 06:08:59 +00:00
1. Items with milestones that have due dates, where the soonest assigned [milestone ](milestones/index.md )
is listed first.
1. Items with milestones with no due dates.
1. Items with a higher priority label.
1. Items without a prioritized label.
2016-06-21 16:54:30 +00:00
2018-02-07 15:17:00 +00:00
Ties are broken arbitrarily.
2016-06-21 16:54:30 +00:00
2018-02-07 15:17:00 +00:00
![Labels sort priority ](img/labels_sort_priority.png )
2020-07-09 03:09:01 +00:00
## Troubleshooting
### Some label titles end with `_duplicate<number>`
In specific circumstances it was possible to create labels with duplicate titles in the same
namespace.
To resolve the duplication, [in GitLab 13.2 ](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21384 )
and later, some duplicate labels have `_duplicate<number>` appended to their titles.
You can safely change these labels' titles if you prefer.
For details of the original problem, see [issue 30390 ](https://gitlab.com/gitlab-org/gitlab/issues/30390 ).