GitLab Scoped Labels

What are they, and why use them?

Welcome to Tanuki Tuesday, where I look at the features offered by GitLab. 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
2. 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.
2. Low
3. Medium
4. 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
2. New Feature
3. 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
2. In Progress
3. Passed
4. 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
2. Accepted
3. Insufficient Detail - this is also used when I or another developer cannot replicate the issue
4. 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), but those few seconds rapidly add up if you've got to add and remove several per issue, over a lot of issues.