Epics provide a way to organize and manage a set of issues and sub-epics that share a strategic theme. In addition to logical grouping, epics enable project managers to perform higher level planning and build a roadmap with visual status tracking.
Key things to know
Epics are defined at the group level
Epics can contain both issues and epics as children
Epics can be used as a filter in both issue lists and issue boards
Epics provide visibility on: child epic and issue status, roadmap timeline (Gantt chart)
An epic provides a roadmap view if it contains one or more child epics which have a start or due date
The roadmap view provides a timeline and completion status based on issue weight completion
The roadmap view is available on the individual epic and on the group page under Epics > Roadmap. The group page view provides additional filtering, sort order and timeline units for display
An issue can only be assigned to one epic
Epics can have multiple child epics up to a depth of 5
Epics cannot be created from templates (issue)
however, there are two workarounds. First - Epics Can be created from an issue that is promoted to an Epic. (in this case, an Issue Template could be a surrogate for an Epic template). Second - The mixture of issues related to an epic can be templatized in a spreadsheet and uploaded to populate the issues related to a given epic. See this epic template overview
The roadmap view can serve as the single source of truth and as a high-level overview to effectively understand the strategic themes and OKRs the team is working on.
A single link to the parent epic or to a group's roadmap page with optional filtering can be used to
Milestones and issue boards can then be used to drill down into the details for more granularity on individual task status.
Associate all related epics in an ancestor relationship
All epics that are related to an OKR epic or a strategic theme epic should have one of them as the ultimate ancestor in order to align them to the roadmap.
Set the start and end date for epics
In order for the roadmap view to be displayed and to provide meaningful visual timeline information, explicitly add the start and end dates to epics during the planning process.
Use executive theme labels
All epics that are part of a strategic theme or an OKR should at the carry their associated executive label, so that they can be filtered on the roadmap view. Optionally they can also carry one or more of the approved group-level labels.
Define weight for child issues
As an additional piece of information to track completion status, the roadmap offers a completion percentage based on the weight of the children issues that have been completed over the total issue weight of all direct descendant issues combined.
Issue weight can be made relative to the tasks within an issue. As a guideline, use a range of 1 (less amount of work, simple) to 5 (more amount of work, complex) for issue weights. You can also use the /weight <value>quick action to define the weight.
Set health status for child issues
It can be good practice to highlight issues that need attention or might be at risk before a status review. This information can then be displayed on the roadmap view. For this to work, a health status can be assigned to individual issues.
A known limitation is that health status cannot be set via quick actions (issue), but it can still be easily set via the web UI.
GIT is a trademark of Software Freedom Conservancy and our use of 'GitLab' is under license
