This is a work in progress for the Marketing Project Management Simplification project.
Labels are a powerful, flexible way to categorize epics, issues, and merge requests.
When applied appropriately and consistently, Labels enable GitLab users to discover, filter, manage, and report on issues, projects, or epics.
There are two types of labels in GitLab:
(Learn more about Groups and Projects)
By default, Labels are not exclusive. An epic, issue, or merge request can be labeled multiple times by multiple people, supporting many different use cases and views. The exception to this rule is the Scoped Label, which specifies a set of mutually exclusive Labels. When one Scoped Label is applied, it automatically replaces any previous Label in that set. Scoped Labels are used to assign status, support workflows, or otherwise segment items into "either / or" situations.
Since Group-level labels cascade to every sub-group and project beneath them, unrestricted Group-level label creation can cause confusion and clutter. For example, if multiple teams create 'high priority' labels at the group level, all of them would show up in the Label menu for every project within the group.
Group-level Labels should only be used for tracking at the Group level, across multiple projects and/or subgroups. Examples of appropriate group-level labels include:
If you are unsure whether you should create a group-level label or a project-level Label, err on the side of caution and create a project-level Label. You can always promote it to a group-level Label in the future.
When creating a Label name, use the smallest possible number of characters. Labels longer than 25 characters may be truncated in the GitLab UI.
When you create a Label, ensure that the Description field contains the following information:
This information will be presented in a tooltip above the Label throughout the UI.
If you are creating a collection of related Labels, group them using common prefix in the name. For example, if you are creating 'West' and 'East' to describe territories, consider Labels such as 'Sales_Region_West' and 'Sales_Region_East' instead. This will provide immediate context to observers while also grouping your Labels together in the UI.
Labels only work properly when they are applied consistently. Wherever possible, automate the creation of appropriate Labels by adding them to Issue templates.
To minimize clutter and reduce the possibility of incorrect double-counts, always consider creating Scoped Labels to automate Label management, rather than depending on users to remove invalid labels as they assign new ones.
The Triage Bot is an open source project that makes it possible to automate many issue and merge request hygiene tasks to ensure that your projects are more consistently following a process. Use the Triage Bot scripts to minimize the impact of human error, automating proper Labeling and workflow. Common uses of the Triage Bot include identifying missing or improperly applied Labels, notifying issue or merge request owners of Label-related problems, and applying Labels based on predefined criteria.
For more information, please refer to @johnjeremiah's YouTube tutorial.
Deleting a Label will remove all prior associations of that Label with issues or merge requests, which can, in turn, break dependencies. All Label deletions should be performed by the Label's DRI (should be listed in the Label description, as stated above).
If you are the DRI and wish to delete a Label, follow the following steps: