Epics

Epics in GitLab coordinate and track large initiatives by organizing work items into a work hierarchy. Teams use epics in the following ways:

• Break down large features into smaller deliverables that add incremental value.
• Track the progress of related work items with scheduled start and end dates.
• Organize discussions and decisions about feature scope and requirements.
• Create hierarchical structures that connect tasks to strategic goals.
• Build visual roadmaps to monitor progress toward objectives.
• Coordinate work across multiple iterations.

In the Ultimate tier, nested epics provide additional structure through work hierarchies that align with agile frameworks. Break down complex projects into child epics, which can contain their own issues and tasks.

Relationships between epics and other items

The possible relationships between epics and other items are:

• An epic is the parent of one or more issues.
• An epic is the parent of one or more child epics. Ultimate only.
• An epic is linked to one or more tasks, objectives, or key results.
• An epic can be assigned one group milestone. The epic’s own milestone does not affect its dates.
• An epic can inherit its start and due dates from its child items, including the milestones assigned to them.

Example set of relationships:

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD
    accTitle: Epics and issues
    accDescr: How issues and child epics relate to parent epics and lateral relationships to work items

    %% Main structure %%
    Parent_epic -->|contains| Issue1
    Parent_epic -->|contains| Child_epic
    Child_epic -->|contains| Issue2

    %% Additional work items and lateral relationships %%
    Issue1 -- contains --> Task1["Task"]
    Issue2 -- "blocked by" --> Objective1["Objective"]
    Task1 -- blocking --> KeyResult1["Key Result"]

    %% Work items linked to epics and issues %%
    Parent_epic -. related .- Objective1
    Child_epic -. "blocked by" .- KeyResult1

Child issues from different group hierarchies

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

Epics as work items

An epic is a type of work item, so epics appear with issues, tasks, and other work items in the Work items list.

The epics API is deprecated. To move your integrations, see migrate epic APIs to work items.

Related topics

• Manage epics and multi-level child epics.
• Link related epics based on a type of relationship.
• Create workflows with epic boards.
• Turn on notifications for epic events.
• Add an emoji reaction to an epic or its comments.
• Collaborate on an epic by posting comments in a thread.
• Use health status to track your progress.
• Create epic templates to standardize epic descriptions.