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.
GitLab provides Groups, Sub-Groups and Projects to structure your organization's work and grant access to several members at once. For example,
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,
GitLab facilitates planning your work with roadmaps with a start and end date, milestones and labels. For example,
Projects can be used strictly for Issue Tracking, or for development of technology projects including source code, build, test, deploying applications.
| 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. |  ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾ |
| 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. |  ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾ |
| 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. |  |
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.
Explore these two examples of Labels:
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 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 exercises below provide best practices for communicating both.
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:
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:
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:
Other common templated use cases include:
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 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.
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.
The Plan Backend assignment board, where the lists are defined by who will be doing the work on a specific release: https://gitlab.com/groups/gitlab-org/-/boards/631316
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 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. |  ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾ |
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 |  |
| 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. |  ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾ |