Managing multiple product categories in GitLab

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:

• stage::name denotes which issues belong to a given stage. In the demo, I created the stage::plan label. This is especially useful for filtering issue boards. By using the scoped label syntax, we get mutually exclusive labels so an issue or MR can only ever be assigned to a single stage.
• group::name denotes which issues belong to a given cross-functional product team. In the demo, I created group::project management, group::portofolio management, and group::certify, which are the actual groups within GitLab's Plan stage. Again, the use of scoped labels assures mutual exclusivity.
• category::name denotes which issues belong to a given category within a stage. In the demo, I created category::epics, category::issue boards, category::issue tracking, category::requirements management, category::roadmaps, and category::service desk, which are the main categories within the Plan stage.

Labels for tracking workflow and issue types:

• type::name denotes the type of issue. In the demo, I've created type::debt, type::feature, and type::defect. Given an issue can only ever be one type, the use of the scoped label syntax is best.
• workflow::state denotes which workflow state an issue is in. In the demo, I've created workflow::validation backlog, workflow::problem validation, workflow::solution validation, workflow::planning breakdown, workflow::scheduling, workflow::ready for dev, workflow::in dev, workflow::review, and workflow::verification. You can design your workflow however you want, but it is helpful to have a discussion with your team to clarify transitions from one workflow state to another.

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:

• Centralize label management within the top level group. This helps avoid label duplication and keeps all teams on the same page.
• Manage issues via issue boards from the group level and keep issues within the same project as their repository to get the most benefit from GitLab's capabilities.
• Create issue boards for different activities – use milestone lists for a release planning board, use scoped workflow labels for a sprint board, etc.
• Create shared milestones within the top-level group. This allows them to cascade throughout all sub-groups and projects.
• If you use epics, a maximum of three layers of nesting is recommended to avoid confusion and unneccessary complexity.
• Use GitLab triage to create policies to help automate issue management.

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