Group vs Project labels

Welcome to Tanuki Tuesday, where I look at the features offered by GitLab. This week is a quick look at labels again, but this time group vs project labels. I've previously covered scoped labels, and those can be used in conjunction with the content here.

Firstly, what are labels? Labels are a way of categorising issues, epics, and merge requests within GitLab. This can make it easier to see at a glance what is happening, or what needs to happen, with one of those. For instance, I use issue templates to help get the information from stakeholders to help the issue progress. In doing this, I set the template to have default labels which are mostly grey in colour. That way it doesn't matter if I am looking at the issue list or an issue board, I know a lot of grey labels means it needs some form of review and categorisation.

When you create a new project against a user in GitLab there are no labels associated with the project (We'll call it Acme Data API). You can generate a set of default labels at the push of a button. This will give you 8 default labels to allow some basic categorisation. Anything more complicated is going to take more time and thought on your behalf, rather than just getting into the project and creating issues and adding value.

But imagine you aren't that bothered by that for now. You've created all your labels which fit your workflow, everything is nicely labelled and organised. Your project starts to grow and you are asked to build an official SDK or similar for a particular language (let's say JavaScript, and call the project Acme Data JavaScript SDK). Now you need another new project, and have to set up all of the labels all over again. And then maintain the list as it grows on one or other project. Then a request for another SDK comes in (Acme Data Python SDK), and the cycle repeats itself. That is because the labels are specifically at a project level, and the labels were created on that project.

Enter Group Labels

Because the projects are all related to the same project or series of work, it makes sense to put them all in a group. So you create a group (Acme Data). It has no labels to start with, and you can't auto generate them. Instead of creating each label manually by name, start by moving the projects into the group. Do this by going to Settings > General > Advanced > Transfer Project and selecting the new namespace (the one of the group).

When you view the labels for the project, there will be an option to promote the label to be a group label:

Doing so will make that label available to all projects within the group. If a label exists with the same name in other projects, they will be merged to use the single group-level label. Below shows the image of the Acme Data JavaScript SDK labels. The 'bug' label which was just promoted to a group label from the Acme Data API project (above) is no longer shown as being a project specific label (it belongs to just Acme Data the group, not Acme Data / Acme Data JavaScript SDK the project).

Yes, you will need to promote each label which should be move to group level, but you only need to do that from one of the projects, not on all of them. And there's no duplicates if they all have the same names.

If a new project is then created as part of that group (Acme Data PHP SDK), it will automatically inherit any labels which have been promoted to group level.

Using group labels helps ensure a consistent categorisation of issues, epics, and merge requests by utilising the same labels throughout. It also lowers the maintenance and up-keep of projects by not having to copy labels between each project each time.

Labels don't have to be exclusively group or project, the two can work in harmony. For instance, within the Acme Data PHP SDK there may be labels for PHP 7.3, PHP 7.4, and PHP 8.0, as they relate to the specific language of that SDK. They might not be appropriate to be part of the group labels as they wouldn't be useful within the Python or JavaScript SDK projects.

These labels show within the Acme Data PHP SDK labels list, but not in any others. They are also shown with the PHP project namespace, not just the group name.

Conclusion

Labels are an incredibly useful and powerful part of GitLab when it comes to categorising issues and other entities. If they aren't used correctly, they can become a huge headache and maintenance nightmare. One way to get around it would be to create a group any time you start a project which may spawn future supporting projects, but that's not always easy to predict. Using groups for every project could become overwhelming and itself a maintenance nightmare.

Instead promoting projects into groups when there's a clear relationship with another, or when they will all follow the same workflow (such as within an organisation), allows the ability to set up the workflow at an individual project level without affecting other projects. Setting project level labels when in groups allows more granular categorisation at the point at which is needs it without adding additional available labels to other projects.