debian-mirror-gitlab/doc/user/project/labels.md

126 lines
6.6 KiB
Markdown
Raw Normal View History

2016-08-24 12:49:21 +05:30
# Labels
2018-03-17 18:26:18 +05:30
## Overview
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
Labels allow you to categorize issues or merge requests using descriptive titles like `bug`, `feature request`, or `docs`. Each label also has a customizable color. They allow you to quickly and dynamically filter and manage issues or merge requests you care about, and are visible throughout GitLab in most places where issues and merge requests are located.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
## Project labels and group labels
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
In GitLab, you can create project and group labels:
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
- **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.
- In the [future](https://gitlab.com/gitlab-org/gitlab-ce/issues/40915), you will be able to assign group labels to issues and merge reqeusts of projects in [subgroups](../group/subgroups/index.md).
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
## Creating labels
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
>**Note:**
A permission level of `Developer` or higher is required in order to create labels.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
### New project label
2016-09-13 17:45:13 +05:30
2018-03-17 18:26:18 +05:30
To create a **project label**, navigate to **Issues > Labels** in the project.
2016-09-13 17:45:13 +05:30
2018-03-17 18:26:18 +05:30
Click the **New label** button. Enter the title, an optional description, and the background color. Click **Create label** to create the label.
2016-09-13 17:45:13 +05:30
2018-03-17 18:26:18 +05:30
If a project has no labels, you can generate a default set of project labels from its empty label list page:
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
![Labels generate default](img/labels_generate_default.png)
2016-09-13 17:45:13 +05:30
2018-03-17 18:26:18 +05:30
GitLab will add the following default labels to the project:
2016-09-13 17:45:13 +05:30
2018-03-17 18:26:18 +05:30
![Labels default](img/labels_default.png)
2016-09-13 17:45:13 +05:30
2018-03-17 18:26:18 +05:30
### New group label
2016-09-13 17:45:13 +05:30
2018-03-17 18:26:18 +05:30
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.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
Group labels appear in every label list page of the group's child projects.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
![Labels list](img/labels_list.png)
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
### New project label from sidebar
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
From the sidebar of an issue or a merge request, you can create a create a new **project label** inline immediately, instead of navigating to the project label list page.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
![Labels inline](img/new_label_from_sidebar.gif)
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
## Editing labels
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
NOTE: **Note:**
A permission level of `Developer` or higher is required in order to edit labels.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
You can update a label by navigating to **Issues > Labels** in the project ot group and clicking the pencil icon.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
You can delete a label by clicking the trash icon.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
### Promoting project labels to group labels
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
If you are expanding from a few projects to a larger number of projects within the same group, you may want to share the same label among multiple projects in the same group. If you previously created a project label and now want to make it available for other projects, you can promote it to a group label.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
From the project label list page, you can promote a project label to a group label. This will merge all project labels across all projects in this group with the same name into a single group label. All issues and merge requests that previously were assigned one of these project labels will now be assigned the new group label. This action cannot be reversed and the changes are permanent.
2017-08-17 22:00:37 +05:30
2018-03-17 18:26:18 +05:30
![Labels promotion](img/labels_promotion.png)
2017-08-17 22:00:37 +05:30
2018-03-17 18:26:18 +05:30
## Assigning labels from the sidebar
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
Every issue and merge request can be assigned any number of labels. The labels are visible on every issue and merge request page, in the sidebar. They are also visible in the issue board. From the sidebar, you can assign or unassign a label to the object (i.e. label or unlabel it). You can also perform this as a [quick action](quick_actions.md) in a comment.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
| View labels in sidebar | Assign labels from sidebar |
|:---:|:---:|
| ![Labels sidebar](img/labels_sidebar.png) | ![Labels sidebar assign](img/labels_sidebar_assign.png) |
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
## Filtering issues and merge requests by label
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
### Filtering in list pages
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
From the project issue list page and the project merge request list page, you can [filter](../search/index.md#issues-and-merge-requests) by both group labels and project labels.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
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 and project labels.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
![Labels group issues](img/labels_group_issues.png)
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
### Filtering in issue boards
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
- 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).
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
## Subscribing to labels
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
From the project label list page and the group label list page, you can subscribe to [notifications](../../workflow/notifications.md) of a given label, to alert you that that label has been assigned to an issue or merge request.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
![Labels subscriptions](img/labels_subscriptions.png)
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
## Label priority
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
>**Notes:**
>
> - Introduced in GitLab 8.9.
> - Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab-ce/issues/18554) considers changing this.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
Labels can have relative priorities, which are used in the "Label priority" and "Priority" sort orders of the issue and merge request list pages.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
From the project label list page, star a label to indicate that it has a priority. Drag starred labels up and down to change their priority. Higher means higher priority. Prioritization happens at the project level, only on the project label list page, and not on the group label list page. However, both project and group labels can be prioritized on the project label list page since both types are displayed on the project label list page.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
![Labels prioritized](img/labels_prioritized.png)
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
On the project and group issue and merge request list pages, you can sort by `Label priority` and `Priority`, which account for objects (issues and merge requests) that have prioritized labels assigned to them.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
If you sort by `Label priority`, GitLab considers this sort comparison order:
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
- Object with a higher priority prioritized label.
- Object without a prioritized label.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
Ties are broken arbitrarily. (Note that we _only_ consider the highest prioritized label in an object, and not any of the lower prioritized labels. [This discussion](https://gitlab.com/gitlab-org/gitlab-ce/issues/18554) considers changing this.)
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
![Labels sort label priority](img/labels_sort_label_priority.png)
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
If you sort by `Priority`, GitLab considers this sort comparison order:
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
- Object's assigned [milestone](milestones/index.md)'s due date is sooner, provided the object has a milestone and the milestone has a due date. If this isn't the case, consider the object having a due date in the infinite future.
- Object with a higher priority prioritized label.
- Object without a prioritized label.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
Ties are broken arbitrarily.
2016-08-24 12:49:21 +05:30
2018-03-17 18:26:18 +05:30
![Labels sort priority](img/labels_sort_priority.png)