gitlab-org--gitlab-foss/doc/user/project/labels.md

stage	group	info
Plan	Project Management	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

Labels

Overview

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. 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, as well as issue boards.

Project labels and group labels

There are two types of labels in GitLab:

• Project labels can be assigned to issues and merge requests in that project only.
• 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)

Assign and unassign labels

Every issue, merge request and epic can be assigned any number of labels. The labels are managed in the right sidebar, where you can assign or unassign labels as needed.

To assign a label to an issue, merge request or epic:

1. In the label section of the sidebar, click Edit, then:
   • In the list, click the labels you want. Each label is flagged with a checkmark.
   • Find labels by entering a search query and clicking search ({search}), then click on them. You can search repeatedly and add more labels.
2. Click X or anywhere outside the label section and the labels are applied.

You can also assign a label with the /label ~label1 ~label2 quick action.

Label management

Users with a permission level of Reporter or higher are able to create and edit labels.

Project labels

View the project labels list by going to the project and clicking Issues > Labels. The list includes all labels that are defined at the project level, as well as all labels inherited from the immediate parent group. You can filter the list by entering a search query at the top and clicking search ({search}).

To create a new project label:

1. Navigate to Issues > Labels in the project.
2. 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.
3. Click Create label to create the label.

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:

1. Click Edit.
2. 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.
3. Click Create.

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.

CAUTION: Caution: If you delete a label, it is permanently deleted. You will not be able to undo the deletion, and all references to the label will be removed from the system.

Promote a project label to a group label

If you previously created a project label and now want to make it available for other projects within the same group, you can promote it to a group label.

If other projects in the same group have a label with the same title, they will all be merged with the new group label. If a group label with the same title exists, it will also be merged.

All issues, merge requests, issue board lists, issue board filters, and label subscriptions with the old labels will be assigned to the new group label.

CAUTION: Caution: Promoting a label is a permanent action, and cannot be reversed.

To promote a project label to a group label:

1. Navigate to Issues > Labels in the project.
2. Click on the three dots ({ellipsis_v}) next to the Subscribe button and select Promote to group label.

Group labels

View the group labels list by going to the group and clicking Issues > Labels. 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}).

To create a group label, navigate to Issues > Labels in the group and follow the same process as creating a project label.

Create group labels from epics (ULTIMATE)

You can create group labels from the Epic sidebar. The labels you create will 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.

Generate default labels

If a project or group has no labels, you can generate a default set of project or group labels from the label list page. The page will show a Generate a default set of labels button if the list is empty, and clicking it will add the following default labels to the project:

• bug
• confirmed
• critical
• discussion
• documentation
• enhancement
• suggestion
• support

Scoped labels (PREMIUM)

Introduced in GitLab Premium 11.10.

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.

A label is scoped when it uses a special double-colon (::) syntax in the label’s title, for example:

An issue, merge request or epic cannot have two scoped labels, of the form key::value, with the same key. Adding a new label with the same key, but a different value will cause the previous key label to be replaced with the new label.

Example use case:

1. An issue is identified as being low priority, and a priority::low project label is added to it.
2. After more review the issue priority is increased, and a priority::high label is added.
3. GitLab automatically removes the priority::low label, as an issue should not have two priority labels at the same time.

Workflows with scoped labels

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::.

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 across label lists in an issue board, but 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.

This functionality is demonstrated in a video regarding using scoped labels for custom fields and workflows.

Scoped labels with nested scopes

You can create a label with a nested scope by using multiple double colons :: when creating it. In this case, everything before the last :: will be the scope.

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.

Additionally, workflow::backend::review and workflow::frontend::review are valid 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.

Subscribing to labels

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 for that label. You will be notified whenever the label is assigned to an epic, 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.

Label priority

• Introduced in GitLab 8.9.
• Priority sorting is based on the highest priority label only. This discussion considers changing this.

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.

From the project label list page, star a label to indicate that it has a priority.

Drag starred labels up and down the list to change their priority, where higher in the list means higher priority.

On the epic, merge request, and issue list pages (for both groups and projects) you can sort by Label priority or Priority.

If you sort by Label priority, GitLab uses this sort comparison order:

1. Items with a higher priority label.
2. Items without a prioritized label.

Ties are broken arbitrarily. Note that only the highest prioritized label is checked, and labels with a lower priority are ignored. See this related issue for more information.

If you sort by Priority, GitLab uses this sort comparison order:

1. Items with milestones that have due dates, where the soonest assigned milestone is listed first.
2. Items with milestones with no due dates.
3. Items with a higher priority label.
4. Items without a prioritized label.

Ties are broken arbitrarily.

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 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.