Skip to content

Epics

DETAILS: Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

An epic in GitLab represents a significant body of work that can be broken down into smaller, manageable parts. Epics help organize user stories and features into a high-level theme or goal, making them a flexible tool for managing projects of all sizes.

Epics often span multiple iterations or a longer period of time, reaching their conclusion when the defined goals are met. Teams use epics to stay focused and aligned with their project timelines.

In the Ultimate tier, create hierarchical structures to align with various agile frameworks using nested epics. Break down complex projects into more manageable child epics, which can further contain their own sets of issues and tasks. This nested structure helps maintain clarity and ensures all aspects of a project are covered without losing sight of the overarching goals.

Use epics to:

  • Break down large features into smaller deliverables that incrementally add user value.
  • Track the progress of a group of related issues, specifying when the work is scheduled to start and end.
  • Facilitate high-level discussions and collaboration on feature ideas and scope, ensuring alignment with the broader project objectives.
  • Organize complex projects into a hierarchy of work with nested epics, providing a clear structure
  • while connecting items to the larger goals of the project.
  • Collect smaller issues (user stories) for detailed tracking and efficient task management.

By using epics effectively, teams can create visual roadmaps, monitor progress, and achieve their goals in the set time frames, driving successful project outcomes.

Relationships between epics and issues

The possible relationships between epics and issues are:

  • An epic is the parent of one or more issues.
  • An epic is the parent of one or more child epics. Ultimate only.
%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD
accTitle: Epics and issues
accDescr: How issues and child epics relate to parent epics
    Parent_epic --> Issue1
    Parent_epic --> Child_epic
    Child_epic --> Issue2

Also, read more about possible planning hierarchies.

Child issues from different group hierarchies

  • Introduced in GitLab 15.5 with a flag named epic_issues_from_different_hierarchies. Disabled by default.
  • Enabled on GitLab.com in GitLab 15.5.
  • Feature flag epic_issues_from_different_hierarchies removed in GitLab 15.6.

You can add issues from a different group hierarchy to an epic. To do it, paste the issue URL when adding an existing issue.

Roadmap in epics

DETAILS: Tier: Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

If your epic contains one or more child epics that have a start or due date, a visual roadmap of the child epics is listed under the parent epic.

Child epics roadmap

If your administrator enabled the new look for epics:

  • On the Child issues and epics section header, select More actions ({ellipsis_v}) > View on a roadmap.

A roadmap filtered for the parent epic opens.

Related topics