Manage epics (PREMIUM)

This page collects instructions for all the things you can do with epics or in relation to them.

Create an epic

• The New Epic form introduced in GitLab 13.2.
• In GitLab 13.7 and later, the New Epic button on the Epics list opens the New Epic form.
• In GitLab 13.9 and later, you can create a new epic from an empty roadmap.

Prerequisites:

• You must have at least the Reporter role for the epic's group.

To create an epic in the group you're in:

1. Get to the New Epic form:

   • Go to your group and from the left sidebar select Epics. Then select New epic.
   • From an epic in your group, select Epic actions ({ellipsis_v}). Then select New epic.
   • From anywhere, in the top menu, select New... ({plus-square}). Then select New epic.
   • In an empty roadmap, select New epic.

2. Enter a title.

3. Complete the fields.

   • Enter a description.
   • To make the epic confidential, select the checkbox under Confidentiality.
   • Choose labels.
   • Select a start and due date, or inherit them.
   • Select a color.

4. Select Create epic.

The newly created epic opens.

Start and due date inheritance

If you select Inherited:

• For the start date: GitLab scans all child epics and issues assigned to the epic, and sets the start date to match the earliest start date found in the child epics or the milestone assigned to the issues.
• For the due date: GitLab scans all child epics and issues assigned to the epic, and sets the due date to match the latest due date found in the child epics or the milestone assigned to the issues.

These dates are dynamic and recalculated if any of the following occur:

• A child epic's dates change.
• Milestones are reassigned to an issue.
• A milestone's dates change.
• Issues are added to, or removed from, the epic.

Because the epic's dates can inherit dates from its children, the start date and due date propagate from the bottom to the top. If the start date of a child epic on the lowest level changes, that becomes the earliest possible start date for its parent epic. The parent epic's start date then reflects this change and propagates upwards to the top epic.

Epic color

Introduced in GitLab 14.9 with a flag named epic_color_highlight. Disabled by default.

FLAG: On self-managed GitLab, by default this feature is not available. To make it available per group, ask an administrator to enable the feature flag named epic_color_highlight. On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. The feature is not ready for production use.

When you create or edit an epic, you can select its color. An epic's color is shown in roadmaps, and epic boards.

Edit an epic

After you create an epic, you can edit the following details:

• Title
• Description
• Start date
• Due date
• Labels
• Color

Prerequisites:

• You must have at least the Reporter role for the epic's group.

To edit an epic's title or description:

1. Select Edit title and description {pencil}.
2. Make your changes.
3. Select Save changes.

To edit an epic's start date, due date, or labels:

1. Next to each section in the right sidebar, select Edit.
2. Select the dates or labels for your epic.

Reorder list items in the epic description

Introduced in GitLab 15.1.

When you view an epic that has a list in the description, you can also reorder the list items.

Prerequisites:

• You must have at least the Reporter role for the project, be the author of the epic, or be assigned to the epic.
• The epic's description must have an ordered, unordered, or task list.

To reorder list items, when viewing an epic:

1. Hover over the list item row to make the grip icon ({grip}) visible.
2. Select and hold the grip icon.
3. Drag the row to the new position in the list.
4. Release the grip icon.

Bulk edit epics

Users with at least the Reporter role can manage epics.

When bulk editing epics in a group, you can edit their labels.

Prerequisites:

• You must have at least the Reporter role for the parent epic's group.

To update multiple epics at the same time:

1. In a group, go to Epics > List.
2. Select Edit epics. A sidebar on the right appears with editable fields.
3. Select the checkboxes next to each epic you want to edit.
4. Select the appropriate fields and their values from the sidebar.
5. Select Update all.

Delete an epic

Prerequisites:

• You must have the Owner role for the epic's group.

To delete the epic:

1. Select Edit title and description {pencil}.
2. Select Delete. A modal appears to confirm your action.

Deleting an epic releases all existing issues from their associated epic in the system.

WARNING: If you delete an epic, all its child epics and their descendants are deleted as well. If needed, you can remove child epics from the parent epic before you delete it.

Close an epic

Prerequisites:

• You must have at least the Reporter role for the epic's group.

Whenever you decide that there is no longer need for that epic, close the epic by:

• Selecting Close epic.

  

• Using the /close quick action.

Reopen a closed epic

You can reopen an epic that was closed.

Prerequisites:

• You must have at least the Reporter role for the epic's group.

To do so, either:

• Select Reopen epic.

  

• Use the /reopen quick action.

Go to an epic from an issue

If an issue belongs to an epic, you can go to the parent epic with the link in the right sidebar.

View epics list

In a group, the left sidebar displays the total count of open epics. This number indicates all epics associated with the group and its subgroups, including epics you might not have permission to view.

Prerequisites:

• You must be a member of either:
  • The group
  • A project in the group
  • A project in one of the group's subgroups

To view epics in a group:

1. On the top bar, select Main menu > Groups and find your group.
2. On the left sidebar, select Epics.

Who can view an epic

Whether you can view an epic depends on the group visibility level and the epic's confidentiality status:

• Public group and a non-confidential epic: You don't have to be a member of the group.
• Private group and non-confidential epic: You must have at least the Guest role for the group.
• Confidential epic (regardless of group visibility): You must have at least the Reporter role for the group.

Cached epic count

• Introduced in GitLab 13.11 with a flag named cached_sidebar_open_epics_count. Enabled by default.
• Enabled on self-managed and on GitLab.com in GitLab 14.0. Feature flag cached_sidebar_open_epics_count removed.

The total count of open epics displayed in the sidebar is cached if higher than 1000. The cached value is rounded to thousands or millions and updated every 24 hours.

Filter the list of epics

• Filtering by child epics was introduced in GitLab 13.0.
• Filtering by the user's reaction emoji introduced in GitLab 13.11.
• Sorting by epic titles introduced in GitLab 14.1.
• Filtering by milestone and confidentiality introduced in GitLab 14.2 with a flag named vue_epics_list. Disabled by default.
• Enabled on GitLab.com and self-managed in GitLab 14.7.
• Feature flag vue_epics_list removed in GitLab 14.8.
• Filtering by group was introduced in GitLab 15.9.

You can filter the list of epics by:

• Title or description
• Author name / username
• Labels
• Milestones
• Confidentiality
• Reaction emoji
• Groups

To filter:

1. On the top bar, select Main menu > Groups and find your group.
2. On the left sidebar, select Epics.
3. Select the field Search or filter results.
4. From the dropdown list, select the scope or enter plain text to search by epic title or description.
5. Press Enter on your keyboard. The list is filtered.

Filter with the OR operator

OR filtering for labels and authors was introduced in GitLab 15.9 with a flag named or_issuable_queries. Disabled by default.

FLAG: On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to enable the feature flag named or_issuable_queries. On GitLab.com, this feature is not available. The feature is not ready for production use.

When this feature is enabled, you can use the OR operator (is one of: ||) when you filter the list of epics by:

• Authors
• Labels

is one of represents an inclusive OR. For example, if you filter by Label is one of Deliverable and Label is one of UX, GitLab shows epics with either Deliverable, UX, or both labels.

Sort the list of epics

You can sort the epics list by:

• Start date
• Due date
• Title

Each option contains a button that can toggle the order between Ascending and Descending. The sort option and order is saved and used wherever you browse epics, including the Roadmap.

Change activity sort order

Introduced in GitLab 13.2.

You can reverse the default order and interact with the activity feed sorted by most recent items at the top. Your preference is saved via local storage and automatically applied to every epic and issue you view.

To change the activity sort order, select the Oldest first dropdown list and select either oldest or newest items to be shown first.

Make an epic confidential

• Introduced in GitLab 13.0 behind a feature flag, disabled by default.
• Became enabled by default in GitLab 13.2.
• You can use the Confidentiality option in the epic sidebar in GitLab 13.3 and later.

If you're working on items that contain private information, you can make an epic confidential.

NOTE: A confidential epic can only contain confidential issues and confidential child epics. However, merge requests are public, if created in a public project. Read Merge requests for confidential issues to learn how to create a confidential merge request.

Prerequisites:

• You must have at least the Reporter role for the epic's group.

To make an epic confidential:

• When creating an epic: select the checkbox under Confidentiality.
• In an existing epic: on the right sidebar, select Edit next to Confidentiality, and then select Turn on.

In GitLab 15.6 and later, you can also use the /confidential quick action.

Manage issues assigned to an epic

This section collects instructions for all the things you can do with issues in relation to epics.

View issues assigned to an epic

On the Child issues and epics section, you can see epics and issues assigned to this epic. Only epics and issues that you can access show on the list.

You can always view the issues assigned to the epic if they are in the group's child project. It's possible because the visibility setting of a project must be the same as or less restrictive than of its parent group.

View count of issues in an epic

On the Child issues and epics section, under each epic name, hover over the total counts.

The number indicates all epics associated with the project, including issues you might not have permission to.

Add a new issue to an epic

You can add an existing issue to an epic, or create a new issue that's automatically added to the epic.

Add an existing issue to an epic

Minimum required role for the project changed from Reporter to Guest in GitLab 15.8.

You can add existing issues to an epic, including issues in a project from a different group hierarchy. Newly added issues appear at the top of the list of issues in the Child issues and epics section.

An epic contains a list of issues and an issue can be associated with at most one epic. When you add a new issue that's already linked to an epic, the issue is automatically unlinked from its current parent.

Prerequisites:

• You must have at least the Guest role for the issue's project and the epic's group.

To add an existing issue to an epic:

1. On the epic's page, under Child issues and epics, select Add.

2. Select Add an existing issue.

3. Identify the issue to be added, using either of the following methods:

   • Paste the link of the issue.
   • Search for the desired issue by entering part of the issue's title, then selecting the desired match. Issues from different group hierarchies do not appear in search results. To add such an issue, enter its full URL.

   If there are multiple issues to be added, press Space and repeat this step.

4. Select Add.

Create an issue from an epic

Minimum required role for the project changed from Reporter to Guest in GitLab 15.8.

Creating an issue from an epic enables you to maintain focus on the broader context of the epic while dividing work into smaller parts.

Prerequisites:

• You must have at least the Guest role for the issue's project and the epic's group.

To create an issue from an epic:

1. On the epic's page, under Child issues and epics, select Add.
2. Select Add a new issue.
3. Under Title, enter the title for the new issue.
4. From the Project dropdown list, select the project in which the issue should be created.
5. Select Create issue.

The new issue is assigned to the epic.

Remove an issue from an epic

Minimum required role for the project changed from Reporter to Guest in GitLab 15.8.

You can remove issues from an epic when you're on the epic's details page. After you remove an issue from an epic, the issue is no longer associated with this epic.

Prerequisites:

• You must have at least the Guest role for the issue's project and the epic's group.

To remove an issue from an epic:

1. Next to the issue you want to remove, select Remove ({close}). The Remove issue warning appears.
2. Select Remove.

Reorder issues assigned to an epic

Minimum required role for the project changed from Reporter to Guest in GitLab 15.8.

New issues appear at the top of the list in the Child issues and epics section. You can reorder the list of issues by dragging them.

Prerequisites:

• You must have at least the Guest role for the issue's project and the epic's group.

To reorder issues assigned to an epic:

1. Go to the Child issues and epics section.
2. Drag issues into the desired order.

Move issues between epics (ULTIMATE)

• Introduced in GitLab 13.0.
• Minimum required role for the project changed from Reporter to Guest in GitLab 15.8.

New issues appear at the top of the list in the Child issues and epics tab. You can move issues from one epic to another.

Prerequisites:

• You must have at least the Guest role for the issue's project and the epic's group.

To move an issue to another epic:

1. Go to the Child issues and epics section.
2. Drag issues into the desired parent epic in the visible hierarchy.

Promote an issue to an epic

Moved from GitLab Ultimate to GitLab Premium in 12.8.

Prerequisites:

• The project to which the issue belongs must be in a group.
• You must have at least the Reporter role the project's immediate parent group.
• You must either:
  • Have at least the Reporter role for the project.
  • Be the author of the issue.
  • Be assigned to the issue.

You can promote an issue to an epic with the /promote quick action.

NOTE: Promoting a confidential issue to an epic makes all information related to the issue public as epics are public to group members.

When an issue is promoted to an epic:

• If the issue was confidential, an additional warning is displayed first.
• An epic is created in the same group as the project of the issue.
• Subscribers of the issue are notified that the epic was created.

The following issue metadata is copied to the epic:

• Title, description, activity/comment thread.
• Upvotes and downvotes.
• Participants.
• Group labels that the issue already has.
• Parent epic.

Use an epic template for repeating issues

You can create a spreadsheet template to manage a pattern of consistently repeating issues.

For an introduction to epic templates, see GitLab Epics and Epic Template Tip.

For more on epic templates, see Epic Templates - Repeatable sets of issues.

Multi-level child epics (ULTIMATE)

You can add any epic that belongs to a group or subgroup of the parent epic's group. New child epics appear at the top of the list of epics in the Child issues and epics section.

When you add an epic that's already linked to a parent epic, the link to its current parent is removed.

Epics can contain multiple nested child epics, up to a total of 7 levels deep.

The maximum number of direct child epics is 100.

Child epics from other groups

• Introduced in GitLab 15.6 with a flag named child_epics_from_different_hierarchies. Disabled by default.
• Minimum required role for the group changed from Reporter to Guest in GitLab 15.7.
• Cross-group child epics enabled on GitLab.com and self-managed in GitLab 15.9. Enabled by default.
• Feature flag child_epics_from_different_hierarchies removed in GitLab 15.10.

You can add a child epic that belongs to a group that is different from the parent epic's group.

Prerequisites:

• You must have at least the Guest role for both the child and parent epics' groups.
• Multi-level child epics must be available for both the child and parent epics' groups.

To add a child epic from another group, paste the epic's URL when adding an existing epic.

Add a child epic to an epic

Minimum required role for the group changed from Reporter to Guest in GitLab 15.7.

Prerequisites:

• You must have at least the Guest role for the parent epic's group.

To add a new epic as child epic:

1. In an epic, in the Child issues and epics section, select Add > Add a new epic.
2. Select a group from the dropdown list. The epic's group is selected by default.
3. Enter a title for the new epic.
4. Select Create epic.

To add an existing epic as child epic:

1. In an epic, in the Child issues and epics section, select Add > Add an existing epic.

2. Identify the epic to be added, using either of the following methods:

   • Paste the link of the epic.
   • Search for the desired issue by entering part of the epic's title, then selecting the desired match. This search is only available for epics in the same group hierarchy.

   If there are multiple epics to be added, press Space and repeat this step.

3. Select Add.

Move child epics between epics

• Introduced in GitLab 13.0.
• Minimum required role for the group changed from Reporter to Guest in GitLab 15.7.

New child epics appear at the top of the list in the Child issues and epics section. You can move child epics from one epic to another. When you add a new epic that's already linked to a parent epic, the link to its current parent is removed. Issues and child epics cannot be intermingled.

Prerequisites:

• You must have at least the Guest role for the parent epic's group.

To move child epics to another epic:

1. Go to the Child issues and epics section.
2. Drag epics into the desired parent epic.

Reorder child epics assigned to an epic

Minimum required role for the group changed from Reporter to Guest in GitLab 15.7.

New child epics appear at the top of the list in the Child issues and epics section. You can reorder the list of child epics.

Prerequisites:

• You must have at least the Guest role for the parent epic's group.

To reorder child epics assigned to an epic:

1. Go to the Child issues and epics section.
2. Drag epics into the desired order.

Remove a child epic from a parent epic

Minimum required role for the group changed from Reporter to Guest in GitLab 15.7.

Prerequisites:

• You must have at least the Guest role for the parent epic's group.

To remove a child epic from a parent epic:

1. Select Remove ({close}) in the parent epic's list of epics. The Remove epic warning appears.
2. Select Remove.