🎨 Design: Migrating Labels to Namespaces

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

• Close this issue

📣 Overview

We need to investigate the work required to transition labels feature to be tied to a namespace. This means that labels should be available at the project and group level with minimal difference in implementation. Labels exist at various levels today so we should account for what migration/consolidation would look like. The end result of the investigation will be a list of considerations, a backlog of issues and a high-level estimate of effort.

🚀 Proposal

tbc

🎯 Jobs

User stories

• Help me categorize work items so that I can organize, find and track items of interest.
• Help me add metadata to work items so that I can analyze them and report to leadership.
• Help me continuously improve upon how I organize work so that I can be more productive.

Tasks

1. Manage labels in namespace(s) e.g. projects
   • A. Create/edit/delete
   • B. Subscribe/unsubscribe
   • C. Add/remove/order priority
   • D. Promote label to ancestor
   • E. Administer default labels for new namespaces
2. Add/remove label(s) to/from work item(s) e.g. MR, issue, epic
3. Filter/sort/group-by page with label(s) e.g. lists, boards, analytics

🧩 Conceptual model

See conceptual model in Figma →

Current state	Future state
No workspace level labels. Group labels are inherited into child projects. Groups have no visibility over child project labels.	Workspace level labels exist. A parent should have access and visibility to everything from its children.

🔎 Analysis

⭐⭐⭐ SEE FULL ANALYSIS ⭐⭐⭐

1. Manage labels in namespace(s)

A. Create/edit/delete

	Project	Group	Admin
Create
Edit
Delete

Notes:

• The functionality and UI between projects and groups are quite similar.
• Labels can be created directly from the work item (issue, epic, MR) dropdown.
• Similar create, edit and delete functionality between projects & groups.
• Editing a group label from a project label's list jumps up to the group's navigation which can be confusing.
• Admin label creation actually creates the default labels that appear in new projects rather than "workspace-level" labels that are inherited down.
• There is no option to delete a label directly from the edit label page - it has to be done from the list.

B. Subscribe/unsubscribe

Project	Group	Admin
		n/a

Notes:

• Group-level labels viewed at the group level can be subscribed to (get email notifications on updates).
• Labels at the project level that have been inherited from the group level can be subscribed to at either level.
• Users can't choose to subscribe from the create/edit page.
• These buttons and some of the row's UI are not PJs compliant - it could definitely be cleaned up.

C. Add/remove/order priority

Project	Group	Admin
	n/a	n/a

Notes:

• This functionality is only available at the project level.
• Priority is assigned from the label list view. Priority labels bubble up the list. Drag & drop to reorder.
• Majority of pages use cards for list items - but only priority labels can be reordered... this is giving users the wrong signal.
• Users can't choose to add priority from the create/edit page
• Administrators cannot automatically assign priority to the labels generated in new projects

D. Promote label to ancestor

Project	Group	Admin
	n/a	n/a

Notes:

• Only available at the project level
• Ancestor level cannot be selected in the create page... only through the navigation

E. Administer default labels for new namespaces

Create	List

Notes:

• Admin label creation actually creates the default labels that appear in new projects rather than "workspace-level" labels that are inherited down.
• This functionality could be entirely removed if there were workspace level labels and more control over the inheritance.

2. Add/remove label(s) to/from work item(s)

Work item	Page	List	Board
Issue
MR			n/a
Epic

Notes:

• This functionality and UI is pretty much identical across work items and projects/groups.

3. Filter/sort/group-by page with label(s)

Notes:

• Labels typically display their description in a tooltip while hovering ("scoped label" shows too if scoped)
• Often clicking on labels links to relative work item list filtered by specific label
  • Clicking on label in issue board adds it to filter
• Lists, boards and analytics pages can be filtered with label
  • When filtering with more than one label, an AND statement is applied
• Lists (except epic) can be sorted by label priority
• Boards can be scoped to a label (effectively filtering) with edit board functionality
• Boards' columns can be scoped to a label

---

Summary

• Task 1: Manage labels in namespace(s) is the area with the most UX inconsistencies. This is mostly because projects have more functionality than groups.
• Task 2: Add/remove label(s) to/from work item(s) & Task 3: Filter/sort/group-by page with label(s) UX is mostly aligned across work item types at project/group-level.

Merge conflicts

Project-level:

• Promote to group-level can be changed to "promote to ancestor" for namespaces
• Add/order/remove priority can be adopted at the group level before a transition to namespaces
• Subscribe at project-level vs group-level can be merged to subscribe to notifications from this namespace vs ancestor namespaces

Admin-level:

• Label administration feature is only available to self-managed admins atm. With workspace labels and finer-grained controls on how labels are inherited, this functionality will become obsolete.

Inheritance

From #338819 (comment 667830288)

• Labels from a parent Namespace are visible in a child Namespace label list.
• Labels from a child are not visible in a parent's label list but they can be used for filtering & board lists.
• It is difficult to understand where a label comes from when adding labels or filtering.
• There's no such thing as workspace labels currently - admin labels are more like defaults for when new namespaces are created.

Tier

• There is general feature parity across self-managed & SaaS except for the "label administration" feature which is only self-managed.
• Scoped labels are available for GitLab Premium - this should translate over easily to namespaces.
• Creating group labels from the epic sidebar is GitLab Ultimate - this will need to be considered when epics are migrated to the more generic "planning object".

Docs

• Current documentation for labels and labels administration is kick-ass!

Broader namespace questions

• Do users understand namespace/workspace/ancestor terminology? How do we communicate these IA changes to users? ux-research#1608 (closed)
• Do we have a pattern to globally communicate inheritance and information flow? (e.g. workspace/par_namespace/chi_namespace)
• Would it be worthwhile creating generic "list", "board", "table" templates/objects that pull in data from (individual and multiple) workflow items? Instead of reproducing the same functionality multiple times for each work item type.
• Do we have an easy way to fine-grain select/exclude multiple namespaces from our navigation?

💡 Solution ideas

These recommendations focus on consolidating information architecture. They lack first-hand user/market research. Therefore, feedback is very welcome!

Start small

See "start small" concepts

Recommendation	Mockup	Issue
Add a "Order priority labels" tab - specifically where cards can be reordered
Translate cards to a table or list view in "all" and "subscribed" tabs
Add an "inherited labels" tab
Change sorting dropdown to a proper sorting component		#345426
Show label inheritance location in tooltips
Add a delete button to the edit label pages		#345195 (closed)
Simplify action buttons - Declutter the page and make PJs compliant		#345630

Think big

Figma prototype →

See "think big" concepts

• Introduce a new inheritance model as a breaking change in 15.0:
• Every single label can be managed directly from the workspace level.
• Namespace-level can manage its own level and children, and it can see what's been inherited.
• If a parent has visibility to everything from its children, we will need to give users a much more sophisticated set of tools to browse, organise and refine their labels.

Recommendation	Mockup	Issue
Fine-grained namespace selection - It is worth exploring this pattern in the left-nav rather than in filter dropdowns.
Switch between optimized views for bulk editing, ordering priority and browsing label inheritance
Table view - Bulk creation/editing of labels directly from the label table
Priority sorting view - Sorting out priority order of labels
Tree view - Browse hierarchy of labels, inheritance and information flow
Filters - Specific dropdowns make filter quicker and more sophisticated
Inheritence controls - Could start with something simple like share/no share and evolve to RBAC.

Related ideas

See related ideas

Recommendation	Mockup	Issue
Batch creation of scoped labels
Suggest labels for work items
Hide/show labels in work item lists
Drag & drop labels and other metadata into the filter bar on work item lists.