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.
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:
- Go to Epics
- Click the New epic button at the top right
- Enter a descriptive title and hit Create epic
Once created, you will be taken to the view for that newly-created epic where you can change its title, description, start date, and due date.
An epic contains a list of issues, and an issue can be associated with at most one epic. You can add issues associated with the epic by clicking the plus icon (+) under the epic description, pasting the link of the issue, and clicking Add. Any issue belonging to a project in the epic's group or any of the epic's subgroups are eligible to be added. To remove an issue from an epic, simply click on the x button in the epic's issue list.
When you add an issue to an epic that's already associated with another epic, the issue is automatically removed from the previous epic. In other words, an issue can be associated with at most one epic.
Start date and due date
For each of the dates in the sidebar of an epic, you can choose to either:
- Enter a fixed value.
- Inherit a dynamic value called "From 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 attached 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 in that if milestones are re-assigned to the issues, if the milestone dates change, or if issues are added or removed from the epic, then the the re-calculation will happen immediately to set a new dynamic date.
Reordering issues in an epic
Drag and drop to reorder issues in an epic. New issues added to an epic appear at the top of the list.
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
Whenever you decide that there is no longer need for that epic, close the epic using the close button:
You can always reopen it using the reopen 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.
Promoting an issue to an epic
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
Only issues from projects that are in groups can be promoted.
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.
- 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
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.
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.
- Comments: collaborate on that epic by posting comments in its thread. These text fields also fully support GitLab Flavored Markdown.
Comment, or start a discussion
Once you wrote your comment, you can either:
- Click "Comment" and your comment will be published.
- Click "Start discussion": start a thread within that epic's thread to discuss specific points.
- You can award an emoji to that epic or its comments.