Skip to content

Epics (ULTIMATE)

Introduced in GitLab Ultimate 10.2.

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.

epics list view

Use cases

  • Suppose your team is working on a large feature that involves multiple discussions throughout different issues created in distinct projects within a Group. With Epics, you can track all the related activities that together contribute to that single feature.
  • Track when the work for the group of issues is targeted to begin, and when it is targeted to end.
  • Discuss and collaborate on feature ideas and scope at a high level.

Creating an epic

A paginated list of epics is available in each group from where you can create a new epic. The list of epics includes also epics from all subgroups of the selected group. From your group page:

  1. Go to Epics.
  2. Click New epic.
  3. Enter a descriptive title and click Create epic.

You will be taken to the new epic where can edit the following details:

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

An epic's page contains the following tabs:

  • Epics and Issues: epics and issues added to this epic. Child epics, and their issues, are shown in a tree view.
    • Click on the > beside a parent epic to reveal the child epics and issues.
    • Hover over the total counts to see a breakdown of open and closed items.
  • Roadmap: a roadmap view of child epics which have start and due dates.

epic view

Adding an issue to an epic

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

Adding an existing issue to an epic

Existing issues that belong to a project in an epic's group, or any of the epic's subgroups, are eligible to be added to the epic. Newly added issues appear at the top of the list of issues in the Epics and Issues tab.

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

To add an issue to an epic:

  1. Click Add an issue.

  2. 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. (From GitLab 12.5)

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

  3. Click Add.

Creating an issue from an epic

Introduced in GitLab 12.7.

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

To create an issue from an epic:

  1. On the epic's page, under Epics and Issues, click the arrow next to Add an issue and select Create new issue.
  2. Under Title, enter the title for the new issue.
  3. From the Project dropdown, select the project in which the issue should be created.
  4. Click Create issue.

To remove an issue from an epic:

  1. Click on the x button in the epic's issue list.
  2. Click Remove in the Remove issue warning message.

Multi-level child epics

Introduced in GitLab Ultimate 11.7.

Any epic that belongs to a group, or subgroup of the parent epic's group, is eligible to be added. New child epics appear at the top of the list of epics in the Epics and Issues tab.

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

An epic can have multiple child epics with the maximum depth being 5.

To add a child epic to an epic:

  1. Click Add an 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. (From GitLab 12.5)

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

  3. Click Add.

To remove a child epic from a parent epic:

  1. Click on the x button in the parent epic's list of epics.
  2. Click Remove in the Remove epic warning message.

Start date and due date

To set a Start date and Due date for an epic, select one of the following:

  • Fixed: Enter a fixed value.
  • From milestones: Inherit a dynamic value from the issues added to the epic.
  • Inherited: Inherit a dynamic value from the issues added to the epic. (Introduced in GitLab 12.5 to replace From milestones).

Milestones

If you select From milestones for the start date, GitLab will automatically set the date to be earliest start date across all milestones that are currently assigned to the issues that are added to the epic. Similarly, if you select From milestones for the due date, GitLab will set it to be the latest due date across all milestones that are currently assigned to those issues.

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

  • Milestones are re-assigned to the issues.
  • Milestone dates change.
  • Issues are added or removed from the epic.

Inherited

If you select Inherited for the start date, GitLab will scan all child epics and issues assigned to the epic, and will set the start date to match the earliest found start date or milestone. Similarly, if you select Inherited for the due date, GitLab will set the due date to match the latest due date or milestone found among its child epics and issues.

These are dynamic dates 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, then the parent epic's start date will reflect the change and this will propagate upwards to the top epic.

Roadmap in epics

Introduced in GitLab Ultimate 11.10.

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

Child epics roadmap

Reordering issues and child epics

Introduced in GitLab 12.5.

New issues and child epics are added to the top of their respective lists in the Epics and Issues tab. You can reorder the list of issues and the list of child epics. Issues and child epics cannot be intermingled.

To reorder issues assigned to an epic:

  1. Go to the Epics and Issues tab.
  2. Drag and drop issues into the desired order.

To reorder child epics assigned to an epic:

  1. Go to the Epics and Issues tab.
  2. Drag and drop epics into the desired order.

Updating epics

Using bulk editing

To apply labels across multiple epics:

  1. Go to the Epics list.
  2. Click Edit epics.
    • Checkboxes will appear beside each epic.
    • A sidebar on the right-hand side will appear, with an editable field for labels.
  3. Check the checkbox beside each epic to be edited.
  4. Select the desired labels.
  5. Click Update all.

bulk editing

Deleting an epic

NOTE: Note: To delete an epic, you need to be an Owner of a group/subgroup.

When inside a single epic view, click the Delete button to delete the epic. A modal will pop-up to confirm your action.

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

Closing and reopening epics

Using buttons

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

close epic - button

You can always reopen it using the reopen button.

reopen epic - button

Using quick actions

You can close or reopen an epic using Quick actions

Navigating to an epic from an issue

If an issue belongs to an epic, you can navigate to the containing epic with the link in the issue sidebar.

containing epic

Promoting an issue to an epic

Introduced in GitLab Ultimate 11.6.

If you have permissions to close an issue and create an epic in the parent group, you can promote an issue to an epic with the /promote quick action. Only issues from projects that are in groups can be promoted. When attempting to promote a confidential issue, a warning will display. Promoting a confidential issue to an epic will make all information related to the issue public as epics are public to group members.

When the quick action is executed:

  • 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 will be copied to the epic:

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

Searching for an epic from epics list page

Introduced in GitLab Ultimate 10.5.

You can search for an epic from the list of epics using filtered search bar (similar to that of Issues and Merge requests) based on following parameters:

  • Title or description
  • Author name / username
  • Labels

epics search

To search, go to the list of epics and click on the field Search or filter results.... It will display a dropdown menu, from which you can add an author. You can also enter plain text to search by epic title or description. When done, press Enter on your keyboard to filter the list.

You can also sort epics list by:

  • Created date
  • Last updated
  • Start date
  • Due date

Each option contains a button that can toggle the order between ascending and descending. The sort option and order will be persisted to be used wherever epics are browsed including the roadmap.

epics sort

Permissions

If you have access to view an epic and have access to view an issue already added to that epic, then you can view the issue in the epic issue list.

If you have access to edit an epic and have access to edit an issue, then you can add the issue to or remove it from the epic.

Note that for a given group, the visibility of all projects must be the same as the group, or less restrictive. That means if you have access to a group's epic, then you already have access to its projects' issues.

You may also consult the group permissions table.

Thread

  • Comments: collaborate on that epic by posting comments in its thread. These text fields also fully support GitLab Flavored Markdown.

Comment, or start a thread

Once you wrote your comment, you can either:

  • Click "Comment" and your comment will be published.
  • Click "Start thread": start a thread within that epic's discussion to discuss specific points.

Award emoji

Notifications