GitLab Agile Portfolio Management - Hands-On Lab: Organize and Manage Issues

This Hands-On Guide walks you through creating metadata for issues, as well as creating a description template in GitLab.

Estimated time to complete: 45-60 minutes

Objectives

To help you manage your issues, GitLab provides metadata for each issue. Metadata allows you to define details for an issue such as weight, and due dates. In this lab, you will learn how to view and manage issue metadata.

Epic: Associates the issue with an epic.
Milestone: Milestones in GitLab are a way to track issues and merge requests created to achieve a broader goal in a certain period of time.
Labels: Apply labels to your issue, which are metadata tags that can be used to sort and filter your issues.
Weight: Apply a weight value to your issue to measure the time, complexity, or value a given issue has or costs.
Due date: Use in issues to keep track of deadlines and make sure features are shipped on time.
Iteration: Associate the issue with an iteration to track it over a period of time. This allows teams to track velocity and volatility metrics.

You can learn more about issues and metadata in the documentation.

Task A. Set issue metadata

In your Family Budget Calculator project, click Plan > Issues from the left pane.
Click on the Third-party financial services integration issue that you created in a previous lab.
In the issue’s metadata pane (on the right side of the screen), click Edit next to the Epic field.
Assign this issue to the Investment Tracking epic by clicking on the Investment Tracking in the list.
In the issue’s metadata pane (on the right side of the screen), click Edit next to the Iteration field.
Assign this issue to the first most recent iteration in Team sprints by clicking on it in the list.
In the issue’s metadata pane (on the right side of the screen), click Edit next to the Due date field.
Set the issue due date to 1 week from today’s date by using the calendar.
In the issue’s metadata pane (on the right side of the screen), click Edit next to the Labels field.
Apply the label Status::WIP. Note this replaces the previous Status::Open label, since an issue can’t simultaneously have multiple labels with the same scope (the “Status::” part of the label).

For more information about scoped labels, see the documentation.
In the issue’s metadata pane, click Edit next to the Weight field.
Enter a value of 2, then click away from the metadata pane to set the issue’s weight.
Navigate to Awesome Inc > Software group. In the left pane, click Epics. Click the Investment Tracking epic. Note that the Third-party financial services integration issue appears in the epic’s details page.
In the left pane, click Plan > Iterations. Click the iteration to which you assigned the issue. Note that the Third-party financial services integration issue appears on the iteration’s details page.

Task B. Organize, promote, and link issues and epics

In your Family Budget Calculator project, click Issues in the left pane.
Click your Backend services issue. You realize that, considering the scope of this initiative, this issue would be better suited as an epic, with each To-Do in the description as a separate issue in the epic.
To promote this issue to an epic, use the /promote quick action in the issue’s comment field, then click Comment.

A quick action is a text-based shortcut for common actions that are usually done by selecting buttons or dropdowns in the GitLab user interface. You can enter these commands in the descriptions or comments of issues, epics, merge requests, and commits. For more information about quick actions, click here.

You can also promote an issue to an epic by clicking the vertical ellipsis next to the Edit button, then clicking Promote to epic in the resulting menu.
After applying the quick action, Backend services is now an epic at the Core group level. Note that there is no comment that says ‘/promote’, as quick actions do not leave a comment. Using the breadcrumbs at the top of the page, click your Core subgroup.
In the left pane, click Epics.
Click into your new Backend services epic.
You’d like to link the epic’s To-Do items as individual issues. While you can promote issues into epics, you cannot promote To-Do items into an issues. Instead, you will need to create a new issue for each To-Do item. Under the Child issues and epics tab, click Add > Add a new issue.
Enter Create DB as the issue title.
In the Project dropdown, select Family Budget Calculator, as it is the only project created so far, and all issues must belong to a project.
Click Create issue in the top right corner.
Follow the previous four steps to create the Create service infrastructure and Backend documentation issues, both linked to the Backend services epic.
Click on the Create DB issue.
In the issue’s right metadata pane, assign the issue to the Backend Services Deployed milestone.
Assign the Create service infrastructure and Backend documentation issues to the Backend Services Deployed milestone. So far all issues have been created in the Family Budget Calculator project by necessity. But as requirements grow it may be best to move some issues into more suitable projects.
Navigate to your Software > Core subgroup.
From the Core group landing page, click New project, then Create blank project.
In the Project name field, enter Database
Leave the Visibility Level at the default selection.
Enable the Initialize repository with a README checkbox.
Click Create project.
Return to your Family Budget Calculator project in the Core subgroup.
In the left pane, click Issues.
Click into the Create DB issue.
On the issue’s details page, scroll to the bottom of the right metadata pane and click Move issue.
Select your Database project, then click Move.
See that the project heading and breadcrumbs at the top of the page indicate your issue is now part of the Database project.

Task C. Create and apply a description template

Navigate to your Awesome Inc group by using the breadcrumbs at the top of the page.
In the upper right corner of the group landing page, click New Project.
Click Create blank project.
Enter Description Templates in the Project name section. This project will hold templates that can be used to pre-populate issues and merge requests across the organization.
Enable the Initialize repository with a README checkbox, as we are not importing in a project that already exists from elsewhere. Leave all other options as their default.
Click Create project.
On the project landing page, click the (+) dropdown near the top of the page under the project title.
Click This Directory > New file.
In the File name field, enter .gitlab/issue_templates/technical_spike.md

For the file’s content, paste the following:

## Instructions
Use this issue to capture research that must take place before continued development of a feature.

### Summary
<!--In 2 sentences or fewer, describe the problem to be solved or the question to be answered.  -->

### Impact Statement
<!-- Describe importance of solving the problem. How will it affect the feature or product direction?  -->

### Tasks

- [ ] Assign participants and DRI
- [ ] Apply appropriate priority and team labels
- [ ] Assign to an upcoming product sprint

/label ~"Status::Open"

Notice that the template is using a quick action to assign a label. Whenever this template is used, a label will automatically be assigned when it is created.

Click Commit changes.

Security Warning: Making direct commits on the main branch without a merge request is not recommended for enterprise level projects.
Using the breadcrumbs at the top of the page, navigate back to your Awesome Inc group.
In the left pane, click Settings > General.
Scroll to the Templates section and select Expand.
In the Templates dropdown, select your Description Templates project.
Click Save changes.
Now the template can be applied when creating an issue. Navigate to your Awesome Inc > Software > Core > Database project.
In the left pane, click Plan > Issues.
Click New issue.
In the Title field, type Identify tuning parameters to reduce performance bottlenecks
In the Description field, expand the Choose a template dropdown and select your technical_spike description template.
(Optional): Edit the description to fill in more details about the issue.
Assign the issue to yourself by clicking on the Assign to me link and click Create issue.
Review the pre-populated description and metadata on the issue’s details page.

Suggestions?

If you’d like to suggest changes to the merge request, please submit them via merge request.

Last modified October 21, 2024: Moved PM labs to ILT section (12cf3300)

View page source - Edit this page - please contribute.