diff options
Diffstat (limited to 'doc/user/project/labels.md')
| -rw-r--r-- | doc/user/project/labels.md | 51 |
1 files changed, 49 insertions, 2 deletions
diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 73d61bedde1..bfc3e3a7de0 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -8,9 +8,48 @@ Labels allow you to categorize issues or merge requests using descriptive titles In GitLab, you can create project and group labels: -- **Project labels** can be assigned to issues or merge requests in that project only. +- **Project labels** can be assigned to issues or merge requests in that project only. - **Group labels** can be assigned to any issue or merge request of any project in that group or any subgroups of the group. +## Scoped labels **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9175) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. + +Scoped labels allow teams to use the simple and familiar feature of labels to +annotate their issues, merge requests, and epics to achieve custom fields and +custom workflow states by leveraging a special label title syntax. + +A scoped label is a kind of label defined only by a special double-colon syntax +in the label’s title, using the format `key::value`. For example: + + + +Two scoped labels with the same key but a different value cannot simultaneeously +apply to an issue, epic, or merge request. For example, if an issue already has `priority::3` +and you apply `priority::2` to it, `priority::3` is automatically removed from the issue. + +An issue, epic, or merge request cannot have two scoped labels with the same key. +For example, if an issue is already labeled `priority::3` and you apply the label `priority::2` to it, +`priority::3` is automatically removed. + +### Workflows with scoped labels **[PREMIUM]** + +Suppose you wanted a custom field in issues to track the platform operating system +that your features target, where each issue should only target one platform. You +would then create labels `platform::iOS`, `platform::Android`, `platform::Linux`, +etc., as necessary. 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](issue_board.md#creating-workflows), 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. + ## Creating labels >**Note:** @@ -35,6 +74,9 @@ GitLab will add the following default labels to the project: To create a **group label**, follow similar steps from above to project labels. Navigate to **Issues > Labels** in the group and create it from there. This page only shows group labels in this group. +Alternatively, you can create group labels also from Epic sidebar. Please note that the created label will belong to the immediate group to which epic belongs. + + Group labels appear in every label list page of the group's child projects. @@ -81,7 +123,7 @@ top-right: GitLab will consider the label title and description for the search. -## Filtering issues and merge requests by label +## Filtering issues, merge requests and epics by label ### Filtering in list pages @@ -89,11 +131,16 @@ From the project issue list page and the project merge request list page, you ca From the group issue list page and the group merge request list page, you can [filter](../search/index.md#issues-and-merge-requests) by both group labels (including subgroup ancestors and subgroup descendants) and project labels. +From the group epic list page, you can [filter](../search/index.md#issues-and-merge-requests) by both current group labels as well as decendent group labels. +  ### Filtering in issue boards - From [project boards](issue_board.md), you can filter by both group labels and project labels in the [search and filter bar](../search/index.md#issue-boards). +- From [group issue boards](issue_board.md#group-issue-boards-premium), you can filter by only group labels in the [search and filter bar](../search/index.md#issue-boards). **[PREMIUM]** +- From [project boards](issue_board.md), you can filter by both group labels and project labels in the [issue board configuration](issue_board.md#configurable-issue-boards-starter). **[STARTER]** +- From [group issue boards](issue_board.md#group-issue-boards-premium), you can filter by only group labels in the [issue board configuration](issue_board.md#configurable-issue-boards-starter). **[STARTER]** ## Subscribing to labels |