Tutorial: Set up a group with multiple projects for issue triage

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

<!-- vale gitlab_base.FutureTense = NO -->

Issue triage is the process of categorization according to type and severity. As your project grows and people create more issues, it's worth creating a workflow for how you'll triage incoming issues.

In this tutorial, you'll learn how to set up a GitLab group with multiple projects for this scenario.

To set up GitLab for issue triage in a project:

1. Create a group
2. Create projects inside a group
3. Decide on the criteria for types, severity, and priority
4. Document your criteria
5. Create scoped labels
6. Prioritize the new labels
7. Create a group issue triage board
8. Create issues for features

Before you begin

• If you're using an existing project for this tutorial, make sure you have the Reporter, Developer, Maintainer, or Owner role for the project.
  • If your existing project does not have a parent group, create a group and promote the project labels to group labels.

Create a group

A group is, in essence, a container for multiple projects. It allows users to manage multiple projects and communicate with group members all at once.

To create a new group:

1. In the upper-right corner, select Create new ({{< icon name="plus" >}}) and select New group.
2. Select Create group.
3. Enter the group details.
   • For Group name, enter triage-tutorial.
4. Select Create group at the bottom of the page.

Create projects inside a group

To manage issue-tracking across multiple projects, you need to create at least two projects inside your group.

To create a new project:

1. In the upper-right corner, select Create new ({{< icon name="plus" >}}) and New project/repository.
2. Select Create blank project.
3. Enter the project details:
   • For Project name, enter test-project-1. For more information, see project naming rules.
4. Select Create project at the bottom of the page.
5. Repeat this process to create a second project named test-project-2.

Decide on the criteria for types, severity, and priority

Next, you'll need to determine:

• Types of issues you want to recognize. If you need a more granular approach, you can also create subtypes for each type. Types help categorize work to get an understanding of the kind of work that is requested of your team.
• Levels of priorities and severities to define the impact that incoming work has on end users and to assist in prioritization.

For this tutorial, suppose you've decided on the following:

• Type: Bug, Feature, and Maintenance
• Priority: 1, 2, 3, and 4
• Severity: 1, 2, 3, and 4

For inspiration, see how we define these at GitLab:

• Types and subtypes
• Priority
• Severity

Document your criteria

After you agree on all the criteria, write it all down somewhere your team mates can always access.

For example, add it to a wiki in your project, or your company handbook published with GitLab Pages.

<!-- Idea for expanding this tutorial: Add steps for [creating a wiki page](../../user/project/wiki/_index.md#create-a-new-wiki-page). -->

Create scoped labels

{{< details >}}

• Tier: Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Next, you'll create labels to add to issues to categorize them.

The best tool for this is scoped labels, which you can use to set mutually exclusive attributes.

Checking with the list of types, severities, and priorities you've assembled previously, you'll want to create matching scoped labels.

The double colon (::) in the name of a scoped label prevents two labels of the same scope being used together. For example, if you add the type::feature label to an issue that already has type::bug, the previous one is removed.

[!note] Scoped labels are available in the Premium and Ultimate tier. If you're on the Free tier, you can use regular labels instead. However, they aren't mutually exclusive.

To create each label:

1. In the top bar, select Search or go to and find your group.
2. Select Manage > Labels.
3. Select New label.
4. In the Title field, enter the name of the label. Start with type::bug.
5. Optional. Select a color from the available colors, or enter a hex color value for a specific color in the Background color field.
6. Select Create label.

Repeat steps 3-6 to create all the labels you need. Here are some examples:

• type::bug
• type::feature
• type::maintenance
• priority::1
• priority::2
• priority::3
• priority::4
• severity::1
• severity::2
• severity::3
• severity::4

Prioritize the new labels

Now, set the new labels as priority labels. Doing this ensures that the most important issues show on top of the issue list if you sort by priority or label priority.

To learn what happens when you sort by priority or label priority, see sorting and ordering issue lists.

To prioritize labels:

1. On the Labels page, next to a label you want to prioritize, select Prioritize ({{< icon name="star-o" >}}). This label now appears at the top of the label list, under Prioritized labels.
2. To change the relative priority of these labels, drag them up and down the list. Labels higher in the list get higher priority.
3. Prioritize all the labels you previously created. Make sure that labels of higher priority and severity are higher on the list than those of lower values.

Create a group issue triage board

To prepare for the incoming issue backlog, create an issue board that organizes issues by label. You'll use it to quickly create issues and add labels to them by dragging cards to various lists.

To set up your issue board:

1. Decide on the scope of the board. For example, create a group issue board that you'll use to assign severity to issues.
2. In the top bar, select Search or go to and find your triage-tutorial group.
3. Select Plan > Issue boards.
4. In the upper-left corner of the issue board page, select the dropdown list with the current board name.
5. Select Create new board.
6. In the Title field, enter Issue triage (by severity).
7. Keep the Show the Open list checkbox selected and clear the Show the Closed list one.
8. Select Create board. You should see an empty board.
9. Create a list for the severity::1 label:
   1. In the upper-right corner of the issue board page, select Create list.
   2. In the column that appears, from the Value dropdown list, select the severity::1 label.
   3. At the bottom of the list, select Add to board.
10. Repeat the previous step for labels severity::2, severity::3, and severity::4.

For now, the lists in your board should be empty. Next, you'll populate them with some issues.

Create issues for features

To track upcoming features and bugs, you must create some issues. Issues belong in projects, but you can also create them directly from your group issue board.

Start by creating some issues for planned features. You can create issues for bugs as you find them (hopefully not too many!).

To create an issue from your Issue triage (by severity) board:

1. Go to the Open list. This list shows issues that don't fit any other board list. If you already know which severity label your issue should have, you can create it directly from that label's list. Keep in mind that each issue created from a label list is given that label.

   For now, we'll proceed with using the Open list.

2. On the Open list, select the Create new issue icon ({{< icon name="plus" >}}).

3. Complete the fields:

   • Under Title, enter User registration.
   • Select the project to which this issue applies. We will select test-project-1.

4. Select Create issue.

5. Repeat these steps to create a few more issues.

   For example, if you're building an app, imagine that test-project-1 and test-project-2 refer to the application's backend and frontend. Create the following issues, assigning to projects as you see fit:

   • User registration
   • Profile creation
   • Search functionality
   • Add to favorites
   • Push notifications
   • Social sharing
   • In-app messaging
   • Track progress
   • Feedback and ratings
   • Settings and preferences

Your first triage issue board is ready! Try it out by dragging some issues from the Open list to one of the label lists to add one of the severity labels.

Next steps

Next, you can:

• Tweak how you use issue boards. Some options include:

  • Edit your current issue board to also have lists for priority and type labels. This way, you'll make the board wider and might require some horizontal scrolling.
  • Create separate issue boards named Issue triage (by priority) and Issue triage (by type). This way, you'll keep various types of triage work separate, but will require switching between boards.
  • Set up issue boards for team hand-off.

• Browse issues by priority or severity in issue lists, filtered by each label. If it's available to you, make use of the "is one of" filter operator.

• Break the issues down into tasks.

• Create policies that help automate issue triage in a project with the gitlab-triage gem. Generate summary reports with heatmaps like the following:

To learn more about issue triage at GitLab, see issue triage and triage operations.