GitLab Scoped Labels
Tags: gitlab
Published: 2021-01-15 09:46:55

## What are they, and why use them?

Welcome to [Tanuki Tuesday](https://www.garybell.co.uk/tag/tanuki-tuesday/), where I look at the features offered by [GitLab](https://about.gitlab.com). This week I'm going to look at scoped labels, and how they can help you streamline your workflow and minimise confusion. Please be aware, this feature is only available on Silver/Premium subscriptions or higher ($19 per user per month).

I have to start by saying I absolutely love scoped labels.
They were the primary driving force for me pushing to upgrade my company's subscription from Bronze to Silver. I use them every day, and they save me a lot of time.

### What are scoped labels?
Scoped labels are a way of categorising labels, so that only one of that category can be used at any given time. This lets you build workflow around the labels, and prevent things being double-labelled in a way which leads to confusion.

By using scoped labels, it would not be possible for something to be categorised `Priority::Low` and `Priority::High` at the same time. That is important as, seeing an issue allocated both high and low priority is going to be confusing. It is going to require someone to spend time looking at the issue, understanding the information and context, and then determining which of the two it would be.

It is important to note that labelling an issue `Priority::Low` does not stop you then giving it the label `Priority::High`, but when you do so the `Priority::Low` label will be automatically removed.

### Configuring Scoped Labels
As shown above, the scope of a label is separated by a double-colon `::`. Everything up to the final `::` is part of the same scope. `Priority::Low` is within the scope of `Priority`, and an issue or merge request can only have one `Priority`. Things get slightly more complicated when adding multiple levels i.e. more than one set of `::` present.

Assume you had issues which needed work from multiple teams e.g. `Frontend`, `Backend`, `Infrastructure`, `Security`. To visualise where the issue sat with each team you might then have statuses `todo`, `in progress`, `review`, `complete`. An issue could then labels `Team::Backend::review`, `Team::Infrastructure::in progress`, and `Team::Security::todo` all at the same time. It would not be possible to allocate labels `Team::Backend::review` and `Team::Backend::complete`, as the scope is the same.

When combined with different colours for the label, it becomes easy to determine a lot of information about an issue without having to read and digest each and every label. I always aim to colour labels of the same scope in shades of the same colour, which helps me visualise where in a given scope it sits.

### Use cases for scoped labels
There's likely a lot of creative ways to use scoped labels, and each will likely depend on the workflow of an individual, business, or project. Here are some useful ways they could be quickly implemented, based on the way I work:

#### Issue Priorities
I gave issue priority as an example when explaining what scoped labels were. To reduce cognitive load when looking at a list of issues, I find it useful to split priorities into sub-scopes:
1. `Priority::Bug`
1. `Priority::Feature`

Both of these get the following 4 labels:
1. TBC - this is always grey. It shows that it needs reviewing and categorising before they can be worked on.
1. Low
1. Medium
1. High

This introduces a risk of something being labelled as a high priority bug *and* a low priority feature. I find that to be a better alternative than a whole board turning red (bug priority colour scheme) when there's a mix of features and bugs with high priority using the same label. The issues this may cause are mitigated by...

#### Issue Type
Issues can be split into different types. I tend to use:

1. Bug
1. New Feature
1. Change Request

By setting these types against the scope `Issue Type::` they can only be allocated a single one of these, which helps clear any ambiguity arising from double-labelling around issue priority.

#### Status
I use status to let items become a critical part of workflow. I can see what my team is working on, and what has been completed because of the labels. To prevent something being `To Do`, `In Progress`, and `For Review` at the same time, these get scoped as `Status::`.

I also use an additional level of status here for testing. This is sub-scoped as `Status::Testing::` with labels in that scope being:
1. To Test
1. In Progress
1. Passed
1. Failed

I use a status of `To Spec` (again, always grey in colour) to let me visually see it needs attention from myself before it enters the main work stream.

#### Bug Status
Separate from the status elements above, I use scoped labels to help triage bugs or issues raised by users. These break down into:
1. New - this is the grey status here. It's not been reviewed or triaged, so needs attention
1. Accepted
1. Insufficient Detail - this is also used when I or another developer cannot replicate the issue
1. Rejected

It's not possible to have a bug accepted into the work stream when it also has insufficient detail and/or cannot be replicated. Once a bug has been accepted, it will be given the label `Status::To Spec` so it can enter a different workflow for progression.

### Conclusion
Scoped labels are a simple feature, but incredibly powerful when used to manage the flow of work through the pipeline. They can provide a useful visual clue as to what is being done, or what needs to be done, on an issue by simple colouring. Huge time savings can be made using scoped labels due to way scopes override any matching scope already on the issue. It doesn't take a lot of time to search for a label and click to remove it (less so with the [click to delete feature](https://about.gitlab.com/releases/2020/10/22/gitlab-13-5-released/#remove-issue-labels-with-a-single-click)), but those few seconds rapidly add up if you've got to add and remove several per issue, over a lot of issues.