diff options
Diffstat (limited to 'doc/user/project/labels.md')
| -rw-r--r-- | doc/user/project/labels.md | 68 |
1 files changed, 38 insertions, 30 deletions
diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 0d02b89be7e..4f0354f86af 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # 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 @@ -32,18 +30,25 @@ There are two types of labels in GitLab: ## Assign and unassign labels -Every issue, merge request and epic can be assigned any number of labels. The labels are +> 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 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: +To assign or unassign a label: -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. -1. Click **X** or anywhere outside the label section and the labels are applied. +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. -You can also assign a label with the [`/label ~label1 ~label2` quick action](quick_actions.md). +Alternatively, to unassign a label, click the **X** on the label you want to unassign. + +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`. ## Label management @@ -52,10 +57,13 @@ and edit labels. ### Project labels -View the project labels list by going to the project and clicking **Issues > Labels**. +> Showing all inherited labels [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241990) in 13.5. + +To view the project labels list, navigate to the project and click **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}**). +labels defined by its ancestor groups. +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}**). To create a new project label: @@ -83,19 +91,19 @@ a label by clicking the three dots (**{ellipsis_v}**) next to the **Subscribe** 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. +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. #### 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. +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. 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. +with the old labels are assigned to the new group label. CAUTION: **Caution:** Promoting a label is a permanent action, and cannot be reversed. @@ -108,7 +116,7 @@ To promote a project label to a group label: ### Group labels -View the group labels list by going to the group and clicking **Issues > Labels**. +To view the group labels list, navigate to the group and click **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}**). @@ -118,15 +126,15 @@ follow the same process as [creating a project label](#project-labels). #### Create group labels from epics **(ULTIMATE)** -You can create group labels from the Epic sidebar. The labels you create will +You can create group labels from the epic sidebar. The labels you create 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). ### 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 +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 to the project: - `bug` @@ -149,13 +157,13 @@ 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. +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. -Example use case: +For example: 1. An issue is identified as being low priority, and a `priority::low` project label is added to it. @@ -188,7 +196,7 @@ This functionality is demonstrated in a video regarding ### 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. +it. In this case, everything before the last `::` is 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 @@ -202,13 +210,13 @@ both have different scopes, `workflow::frontend` and `workflow::backend`. 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 -label. You will be notified whenever the label is assigned to an epic, +label. You are 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 @@ -222,7 +230,7 @@ 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. |