The Ultimate Manual To GitLab Issues

You can build software and run projects in various ways. If you choose to do it within GitLab, you have probably wondered how to build tools that can support a diverse array of workflows without crippling users with complexity.

The best way to ensure this is to build fewer, more flexible tools. 

A shining example is GitLab’s Issue which allows you to decide how to build a single, versatile tool that can help users significantly reduce complexity and tooling maintenance without restricting its capabilities.

What are GitLab Issues Anyway?

The GitLab platform lets you use Issues to collaborate on ideas, plan workflows, and solve problems. You can also share and discuss proposals with your team members and with stakeholders and outside collaborators.

Issues are also versatile, serving many purposes customized to your needs and workflow. This includes:

• Discussing idea implementation
• Task and work status tracking
• Accepting feature proposals, support requests, questions, or bug reports
• Elaborating on code implementations

Generally, GitLab Issues are always associated with a specific project. If you have various projects in a group, you can view all of the project’s Issues at once.

What are the Different Issue Types?

When a new resource type gets added, often it isn’t clear if it’s an extension of an Issue (Issue type) or a new first-class resource type (similar to Issue, merge request, epic, snippet). 

That’s where an Issue type comes into the picture. 

An Issue type is a resource type extending the existing Issue type and can be used anywhere where an Issue is used, such as when linking objects of the type from Epics or when listing or searching Issues.

Generally, an Issue type can be used in the following two cases:

• When the new type is usable anywhere where the basic Issue type is used
• When the new type only adds new fields to the basic Issue type — but without eliminating existing fields

How GitLab Issues Works

Issues have certain unique traits you should know about to use the GitLab platform more effectively.

First and foremost, Issues are defined in the scope of a project and not a group. In other words, they only exist in projects. Groups have boards that manage Issues and a list of Issues, but the Issues are always stored in a project that is subordinate to the group. In reality, GitLab Groups have Epics. 

Next, let’s look at the terminology associated with GitLab Issues.

Issue Descriptions

A description is the top section of an Issue, also known as the body of the Issue. It’s whether the themes and topics of the Issue are noted.

Lengthy Issue descriptions aren’t uncommon and are encouraged to capture the most recent status of the Issue. As Issue discussions are often long and flowing, we recommend keeping the description up to date regularly.

Issue Details

An Issue has various detailed parts, including:

• Time tracking – Time tracking lets you estimate and track the time spent on Issues and merge requests. With this feature, you can then view reports showing totals over time when performing tasks.
• Weight – Getting an overview becomes challenging when you have a lot of Issues. With weighted Issues, you can get a better idea of how much time, value, and complexity a given Issue has or costs.
• Participants and notifications – Notification emails allow you to stay informed about what’s happening in GitLab. You can receive updates about activity in Issues, merge requests, design, and epics.
• Mentions – Mention a group or user in your GitLab instance with @groupname and @username, respectively. Everyone mentioned will be notified about the to-do items and emails. What’s more, you can highlight comments mentioning you in a different color.
• Linked Issues – Linked Issues refer to the bi-directional relationship between two Issues and appear in a block below the Issue description. Linking Issues in different projects is another feature that GitLab offers.
• Merge requests – Mentioning Issues in merge request comments works similarly to linked Issues. So, when you mention an Issue in a merge request description, it’ll directly link the Issue and merge request together. An Issue will be closed automatically once the merge request is merged.
• Comments and threads – Communication is incredibly easy on GitLab, thanks to comments, threads, and code suggestions. You have two types of comments on the platform: a standard comment and a comment in a thread that can be resolved. Here, you can enter markdown and use quick actions — or suggest code changes in your commit diff comment that the user can accept through the user interface. 

Task Lists

In the Markdown language when writing descriptions and comments on Issues, you can create a list of items that work as checkboxes. Think of it as a list of tasks, meaning task lists are a relatively simple list of items that can be ‘checked off.‘

Quick Actions

Issues, merge requests, and ethics are all designed to support keyboard shortcuts that trigger key actions in the Issue, merge requests, or epic.

Essentially, quick actions or commands help users easily change an Issue. These include:

• /label followed by the label name will add a label.
• /assign followed by a user ID will assign the Issue to a person
• /close will close an Issue
• /duplicate followed by an Issue number will close the current Issue as a duplicate and link to the given (open) Issue
• /epic followed by an epic ID will assign the Issue to an epic

Related Issues and Blocking Issues

To effectively manage interdependence between Issues, we need to create several types of relationships between Issues, such as:

• Simple relationships: Where one Issue is simply related to another Issue and there’s no interdependency.
• Blocks: Where one Issue prevents another Issue from getting completed.
• Is blocked by: Where an Issue is dependent on another Issue.

With Issue relationships, you can create a series of tasks/Issues where there’s a sequential requirement that one Issue is completed before the following Issues. 

How to Get Started With GitLab Issue Management

Before you can start collaborating on ideas and planning work, you need to understand how to get started with GitLab Issues. 

Here’s how.

Step 1: Create an Issue

When you create an Issue, you need to enter the fields of the Issue. 

• Title
• Type: either Issue (default) or incident
• Description template: Overwrites anything in the Description text box
• Description: Use Markdown and quick actions here
• Checkbox to make the Issue confidential
• Assignees
• Weight
• Epic
• Due date
• Milestone
• Labels

If you know the values you want to assign to an Issue, you can also use quick actions to make the entry process faster.

There are various ways to create an Issue in GitLab, including:

• From a project
• From a group
• From another Issue or incident
• From an Issue board
• By sending an email
• Using a URL with pre-filled values
• Using service desk

Here are the steps to create an Issue from a project:

1. On the top bar, select Menu. From there, select Projects to locate your project.
2. Here, you can either select Issues on the left sidebar and then click on New Issue in the top right corner of your screen. Or you can go to the top bar, select the plus sign (+) and then, select New Issue under This project. 

This will open the newly created Issue. Keep in mind that to do this, you’ll need at least the Guest role for the project.

Step 2: Edit an Issue

To edit an Issue’s title and description, you need to have at least the Reporter role for the project. Alternatively, you can also be the author of the Issue or be assigned to the Issue.

Here are the steps to edit an Issue:

1. To the right-hand side of the title, select Edit title and description.
2. Edit the available fields.
3. Once done, select Save changes.

You can also re-order the list items in the Issue description, as well as bulk edit Issues from a project or a group.

Step 3: Move an Issue

When you move an Issue, it’s closed and copied to the target project. However, the original Issue isn’t deleted.

A system note indicating where it came from and went to gets added to both Issues. Sometimes, Issues contain sensitive data. If that’s the case, you need to be careful when moving it. Be extra vigilant when moving an Issue to a project with different access rules, too.

Here’s how to move an Issue:

1. Open the Issue.
2. On the right sidebar, click on Move Issue.
3. Look for a project to move the Issue to, and select Move.

Keep in mind you need to have at least the Reporter role for the project to carry out the above steps.

Step 4: Close an Issue

You can close an Issue when it gets resolved or is no longer needed. Note that the Issue is simply marked as closed and not deleted. 

To do this, you need to have at least the Reporter role for the project, be the author of the Issue, or be assigned to the Issue.

Here’s how to close an Issue:

1. At the top of the Issue, select Close Issue.
2. In an Issue board, drag an Issue card from its list into the Closed list. Think of it as shifting a card from one section to another. 

You can also reopen s closed Issue if needed—provided you have at least the Reporter role for the project, be the author of the Issue, or be assigned to the Issue.

To do this, select Reopen Issue at the top of the Issue. The reopened Issue will be no different from any other open Issue.

Step 5: Change the Issue Type

If have at least the Reporter role for the project, the author of the Issue or are assigned to the Issue. 

Here are the steps to change the Issue type follow

1. To the right of the title, select Edit title and description from the displayed options.
2. Edit the Issue and select an Issue type from the Issue type dropdown list.
3. Click Save changes when done. 

While there are a ton of other actions you can do with GitLab Issues, the above are the most prominent. Once everything is done and you want to delete the Issue, select Edit title and description followed by Delete Issue.