101 - No Tissues with Issues

Objective

A quick overview of how to plan and manage regular work using GitLab. The focus of this page is to help you learn how to work with Groups, Projects, Issues and Boards to plan and manage the your work and your team’s work.

Note: If you are only looking for instructions on how to submit an Issue, feel free to skip forward to Issues in Action.

The Big Picture

Organizing

GitLab provides Groups, Sub-Groups and Projects to structure your organization’s work and grant access to several members at once. For example,

  • Group - Account Management
    • Sub-group - Regions - AMS, EMEA, APAC
      • Project - Countries - North America (within AMS), France (within EMEA), Singapore (within APAC)

Organizing your work

Defining

GitLab allows you to group related work in the form of epics, sub-epics and issues - which are the smallest unit of work. For example,

  • Epic - Annual Business planning
    • Sub-epic - Quarterly Business planning (e.g., Q1, Q2, Q3, Q4)
      • Issues - Plan for Individual Customers

Defining your work

Planning

GitLab facilitates planning your work with roadmaps with a start and end date, milestones and labels. For example,

  • Group Roadmap - Timeline for your annual business planning
    • Group Milestone - Key milestones during your planning - e.g., Start and end dates for Q1, Q2, Q3, Q4 planning
      • Project Milestone - Deployment milestones for a specific customer

Planning your work

Doing the work

Projects can be used strictly for Issue Tracking, or for development of technology projects including source code, build, test, deploying applications.

Doing the work

Bringing it all together

GitLab Agile Planning & Reporting Structure

The Details

GitLab Groups

In order to manage multiple projects (portfolios of projects), the GitLab Group is the entity that enables strategic planning and tracking of business initiatives through delivery. At the Group Level, you can manage sub-groups, projects, epics, milestones, roadmaps and group level boards. Groups With GitLab Groups you can assemble related projects together and grant members access to several projects at once. Groups can also be nested in subgroups.

GitLab Group

GitLab “Project”

The project in GitLab is the core building block, where work is organized, managed, tracked and delivered. A project in GitLab enables the team to collaborate and plan their work in the form of Issues (use cases/requirements), Issue boards (Kanban), and Milestones (Sprints). With Projects in GitLab, you can create projects for hosting your codebase, use it as an issue tracker, collaborate on code, and continuously build, test, and deploy your app with built-in GitLab CI/CD. Your projects can be available publicly, internally, or privately, at your choice. GitLab does not limit the number of private projects you create.

GitLab Project

The GitLab Project is much, much, much more than simply project management. The GitLab project unlocks the power of an industry leading source code management repository and a CI/CD pipeline. The Merge Request is the linkage between the issue and the actual code changes. The merge request captures the design, implementation details (code changes), discussions (code reviews), approvals, testing (CI Pipeline), and security scans.

GitLab Repository

Group vs Project

Group

  • Groups are like ‘folders’

GitLab Group

Project

  • Projects have many ’things’ like issues, repositories, merge requests, etc.

GitLab Project

Hands on: Explore Groups and Projects

Labels

The label in GitLab is a flexible and powerful mechanism to tag and track work. Labels are used to define columns in the issue boards and make it easy to search and find issues or merge requests related to a common theme. Labels can be defined at EITHER Group or Project level

Labels allow you to categorize issues or merge requests using descriptive titles like bug, feature request, or docs. Each label also has a customizable color. Labels allow you to quickly and dynamically filter and manage issues or merge requests you care about, and are visible throughout GitLab in most places where issues and merge requests are located.

Hands on: Explore Group and Project Labels

Explore these two examples of Labels:

Issue

The issue in GitLab is the fundamental planning object. It is where the team documents the use case in the description, discusses the approach, estimates the size/effort (issue weight), tracks actual time/effort, assigns work, and tracks progress. Labels enable the team to tag issues, track status, and associate issues with different initiatives. Issues are part of a Project

Issues Issues can have endless applications. For example, Issues can be used to; Discuss the implementation of a new idea, Submit feature proposals, Ask questions, Report bugs and so on.

Issues

Issues in Action: Common Use Cases

Issues are appropriate for almost any type of interaction or request—feature suggestions, bug reports, general discussions, and more. Whatever an Issue’s purpose, to use it effectively, the author must communicate two things:

  • The intended audience
  • The information necessary to allow the audience to respond asynchronously

The exercises below provide best practices for communicating both.

Hands on: Create an Ad Hoc Issue

Since Issues live in Projects, the first step to creating an issue is locating the appropriate Project for your topic and audience. In this example, we’ll be creating an ad hoc, free-text issue, asking a question of the Account Based Marketing Team in the GitLab101: Account Based Marketing Sample Project. To create the Issue:

  • Visit the main Project page.
  • Click the Issues link in the left-hand nav to view the Issues List.
  • Click the green New Issue button in the top-right corner of the screen.
  • Add a Title that summarizes your question or comment
  • Type your comment or question in the Description field, as you would an email. The field supports Markdown, which you can preview as you type.
  • You can @mention stakeholders or other interested parties to send them notifications and To-Do list items from this Issue. For this exercise, @mention yourself, to avoid spamming your coworkers with a test message.
  • Assign the issue to yourself. This issue will now be linked to your current Issue list, accessible by clicking the Issues icon at the right corner of the purple toolbar at the top of the page.
  • IMPORTANT: Due to our Transparency value, the default View setting for Issues is public. If your issue contains customer information or other sensitive data, check the checkbox next to “This issue is confidential and should only be visible to team members with at least Reporter access.”
  • Click the green “Submit Issue” link.

Congratulations! You’ve just created an issue. You should receive an email summarizing your Issue, and you can add to the Issue’s conversation simply by replying to that email.

Commonly-used group Issue Boards include:

Hands on: Create a Templated Issue

To minimize the amount of back-and-forth required to provide all necessary information for complex requests, Project owners have created Issue templates for the most common use cases. These templates provide a description of all necessary information and formatting to complete a request. In many cases, they also provide a checklist for the author to review before submitting.

When submitting a templated issue, please take the time to read the entire description and respond to any checkboxes ([ ]) before submitting.

For this exercise, we will create a Sales Enablement request using the Enablement template.

To request an Enablement session:

  • Visit the Product Marketing Group page.
  • Click the Issues link in the left-hand nav to view the Issues List.
  • Click the green New Issue button in the top-right corner of the screen.
  • Select Enablement from the Template drop-down menu and click the orange Apply Template button.
  • Fill out details in each section (for example, “Learning Objectives / Key points”) as completely as you can, adding additional items or removing unused bullets as necessary.
  • Identify stakeholders and other interested parties using @mentions as in the previous exercise.
  • Add a Due Date if you have one. This does not guarantee that work will be delivered by this date, but it adds context for the Project owner who receives and triages this request.
  • Do not remove or modify the /label code at the bottom of the issue. This will assign appropriate Labels to ensure proper routing.
  • Do not assign the issue. This will delay the processing of your request. Each Group within Product and Solution Marketing has a process to triage and assign issues.
  • Since this is an active project, DO NOT click the green Submit Issue button unless you are actually requesting an Enablement session.

Other common templated use cases include:

Requesting Assets
Requesting People
Requesting Event Sponsorship / Support
Account Support and Access

For common licensing, customer access, and technical support issues, please visit the handbook’s Internal Support page for access to the appropriate issue templates.

Boards

Boards provide a flexible and dynamic approach to visually manage a project. Boards make it easy for a team to create lists and move issues from one list to another. List on the board can be defined by a label, assignment, or milestone. Here, teams can manage their backlog of work, prioritize the items, and then move the issues to the team or specific stage in the project. Each list in the board calculates the total size (weights) of the associated issues, enabling the team to understand how much work is assigned at any given time. Boards are available for EITHER Group or Project

Project Issue Boards The GitLab Issue Board is a software project management tool used to plan, organize, and visualize a workflow for a feature or product release. It can be used as a Kanban or a Scrum board. It provides perfect pairing between issue tracking and project management, keeping everything in the same place, so that you don’t need to jump between different platforms to organize your workflow. With GitLab Issue Boards, you organize your issues in lists that correspond to their assigned labels, visualizing issues designed as cards throughout that lists. Boards

The group level issue board makes it possible for oversight and governance of the projects and sub groups. This view, makes it easy to see how specific issues are flowing through the lifecycle and to understand the overall capacity of the teams. GitLab Kanban Board

Hands on: Play with boards

Milestones

Milestones establish a target date for a sprint or specific bundle of issues and code changes to be delivered. The milestone enables the team to either set a specific Start and Stop for the work, as in a Sprint, or the milestone could be a fixed point in time. Milestones are EITHER Group or Project

| Milestones in GitLab are a way to track issues and merge requests created to achieve a broader goal in a certain period of time. Milestones allow you to organize issues and merge requests into a cohesive group, with an optional start date and an optional due date. | Milestone burndown chart ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾ |

Group Level Planning

Epics

In order to track groups of related issues, the GitLab epic gives product owners and leaders the ability to link and manage work over an extended time frame. Planning work use Epics allows you to create parent and child epics. An epic can span multiple milestones and makes it easier to manage the overall flow and priority of work. Epics are GROUP ONLY

| Epics let you manage your portfolio of projects more efficiently and with less effort by tracking groups of issues that share a theme, across projects and milestones | Epics |

Roadmaps

| The roadmap is a visual representation of the various epics for the group. The roadmap view can be filtered by label and organized by start / stop date of the epics in order to visualize the sequence of work. At this point, GitLab doesn’t create dependencies between issues or epics. | GitLab Roadmap‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾ |

Last modified July 29, 2024: Fixing more formatting issues caused by the handbook migration (9b5eccc2)
View page source - Edit this page - please contribute. Creative Commons License