Managing multiple product categories in GitLab

Dec 5, 2019 · 6 min read · Leave a comment
Gabe Weaver GitLab profile

This blog post was originally published on the GitLab Unfiltered blog. It was reviewed and republished on 2019-12-30.

In a recent tweet, a member of the wider GitLab community asked how to set up GitLab so multiple product teams, each with their own unique workflows, could contribute effectively to a single repository. Let's explore some options.

GitLab's approach

Given that GitLab is growing very quickly, we've had to put a lot of thought into organizational structure and mapping to create a well structured workflow within GitLab. The entirety of the product surface area is comprised of seven distinct product sections. Each section consists of several stages, and each stage contains several categories. Our cross-functional product teams are called groups and the groups typically own a handful of categories within a stage. For example, I'm the senior product manager for the Project Management group, which is responsible for the issue tracking, Kanban boards, and time tracking categories. There are two other groups within the Plan stage.

While each product team can technically have their own workflow, we've deliberately tried to standardize across teams. We accomplish this primarily through leveraging group level issue boards and labels. I've created a demo group where you can see the our basic approach setup directly within GitLab. The first step to get up and running is to configure the labels. Within our top level group, we've created specific label sets to help us organize our issues, MRs, and issue boards.

Labels for managing ownership and surface area:

Labels for tracking workflow and issue types:

With our labels in place, we can now spin up some group level issue boards for the different product teams. The Project Management team's issue board uses a common naming convention and is scoped to only include issues that contain the group::project management and stage::plan labels. The lists are set up according to the workflow::* labels we defined earlier. The Portfolio Management and Certify teams use a similar structure. The benefit of standardizing on a workflow is that it allows you to easily move from one team to the next and understand what's going on, as well as create rollup issue boards that cut across many teams. In the demo, I created a stage level issue board for Plan. All of the issues belong to the same project that contains the single repository where all of the product teams contribute.

The last thing to cover is using milestones to align everyone around a shared release cadence. In the demo, I created two group milestones that all of the issues map to. This allows you to see progress at a high level as well as a breakdown of issue status by label type. We're currently working on allowing an issue to be associated to multiple milestones, enabling milestones to have types, and adding burnup charts to milestones. Once these launch, teams will have even more flexibility to create shared milestones as well as team-specific milestones.

Other options

There are a few less desirable ways to setup GitLab to help coordinate multiple product teams:

The project approach

With the project approach, you can create a project for each individual team and disable the repo. Then create a shared repo where all the merge requests go. Each product team would then have its own project-level milestones, issue boards, and issues, but could still nicely tie into the shared repository. Here's an example issue and MR demonstrating how this works. The downside of this approach is that you lose the "Create Merge Request" button that issues will have if the issue and repo are within the same project. The "Create Merge Request" button allows you to quickly bootstrap your work by spinning up a branch and WIP MR. You also lose the ability to accurately track cycle analytics out-of-the-box because it is currently based on project level data and not group level data.

Single issue tracker project

I've seen some teams use a single issue tracker project with multiple repositories within the group. They use a similar labeling system described in GitLab's approach, but separate the concerns of code management from issue management. While this works, it has the same downsides as the project approach.

General best practices & conventions

To sum things up, there are some generally good practices to follow when setting up your organizational structure within GitLab:

If you want to talk shop or bounce around ideas, feel free to reach out via email – gweaver at gitlab dot com.

Cover image by Maksym Kaharlytskyi on Unsplash {: .note}

Guide to the Cloud

Harness the power of the cloud with microservices, cloud-agnostic DevOps, and workflow portability.

Learn more
Git is a trademark of Software Freedom Conservancy and our use of 'GitLab' is under license