2019-09-04 21:01:54 +05:30
---
type: reference, howto
2020-06-23 00:09:42 +05:30
stage: Plan
group: Portfolio Management
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
2019-09-04 21:01:54 +05:30
---
2020-03-13 15:44:24 +05:30
# Epics **(PREMIUM)**
2019-07-31 22:56:46 +05:30
2020-03-13 15:44:24 +05:30
> - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.2.
2020-06-23 00:09:42 +05:30
> - Single-level Epics [were moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8.
2019-07-31 22:56:46 +05:30
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.
2020-05-24 23:13:21 +05:30
<!-- Possibly swap this file with one of a single epic -->
2019-07-31 22:56:46 +05:30
## 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 ](../index.md ). With Epics, you can track all the related activities that together contribute to that single feature.
2020-04-22 19:07:51 +05:30
- Track when the work for the group of issues is targeted to begin, and when it's targeted to end.
2019-12-21 20:55:43 +05:30
- Discuss and collaborate on feature ideas and scope at a high level.
2019-07-31 22:56:46 +05:30
2020-05-24 23:13:21 +05:30
## Manage epics
2020-03-13 15:44:24 +05:30
2020-05-24 23:13:21 +05:30
To learn what you can do with an epic, see [Manage epics ](manage_epics.md ). Possible actions include:
2020-03-13 15:44:24 +05:30
2020-05-24 23:13:21 +05:30
- [Create an epic ](manage_epics.md#create-an-epic )
2020-06-23 00:09:42 +05:30
- [Bulk-edit epics ](../bulk_editing/index.md#bulk-edit-epics )
2020-05-24 23:13:21 +05:30
- [Delete an epic ](manage_epics.md#delete-an-epic )
- [Close an epic ](manage_epics.md#close-an-epic )
- [Reopen a closed epic ](manage_epics.md#reopen-a-closed-epic )
- [Go to an epic from an issue ](manage_epics.md#go-to-an-epic-from-an-issue )
- [Search for an epic from epics list page ](manage_epics.md#search-for-an-epic-from-epics-list-page )
- [Make an epic confidential ](manage_epics.md#make-an-epic-confidential )
- [Manage issues assigned to an epic ](manage_epics.md#manage-issues-assigned-to-an-epic )
- [Manage multi-level child epics **(ULTIMATE)** ](manage_epics.md#manage-multi-level-child-epics-ultimate )
2019-12-21 20:55:43 +05:30
2020-05-24 23:13:21 +05:30
## Relationships between epics and issues
2020-03-13 15:44:24 +05:30
2020-05-24 23:13:21 +05:30
The possible relationships between epics and issues are:
2020-03-13 15:44:24 +05:30
2020-05-24 23:13:21 +05:30
- An epic is the parent of one or more issues.
- An epic is the parent of one or more child epics. For details see [Multi-level child epics ](#multi-level-child-epics-ultimate ). ** (ULTIMATE)**
2020-03-13 15:44:24 +05:30
2020-05-24 23:13:21 +05:30
```mermaid
graph TD
Parent_epic --> Issue1
Parent_epic --> Child_epic
Child_epic --> Issue2
```
2019-07-31 22:56:46 +05:30
2020-05-24 23:13:21 +05:30
See [Manage issues assigned to an epic ](manage_epics.md#manage-issues-assigned-to-an-epic ) for steps
to add an issue to an epic, reorder issues, move issues between epics, or promote an issue to an epic.
2019-07-31 22:56:46 +05:30
2020-04-22 19:07:51 +05:30
## Issue health status in Epic tree **(ULTIMATE)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199184) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10.
You can report on and quickly respond to the health of individual issues and epics by setting a
red, amber, or green [health status on an issue ](../../project/issues/index.md#health-status-ultimate ),
which will appear on your Epic tree.
### Disable Issue health status in Epic tree
This feature comes with a feature flag enabled by default. For steps to disable it, see
[Disable issue health status ](../../project/issues/index.md#disable-issue-health-status ).
2020-03-13 15:44:24 +05:30
## Multi-level child epics **(ULTIMATE)**
2019-07-31 22:56:46 +05:30
2020-06-23 00:09:42 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8333) in GitLab Ultimate 11.7.
2019-07-31 22:56:46 +05:30
2020-05-24 23:13:21 +05:30
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.
2019-12-21 20:55:43 +05:30
2020-04-22 19:07:51 +05:30
When you add an epic that's already linked to a parent epic, the link to its current parent is removed.
2019-12-21 20:55:43 +05:30
2020-05-24 23:13:21 +05:30
An epic can have multiple child epics up to the maximum depth of five.
2019-12-26 22:10:19 +05:30
2020-05-24 23:13:21 +05:30
See [Manage multi-level child epics ](manage_epics.md#manage-multi-level-child-epics-ultimate ) for
steps to create, move, reorder, or delete child epics.
2019-07-31 22:56:46 +05:30
## Start date and due date
2019-12-26 22:10:19 +05:30
To set a **Start date** and **Due date** for an epic, select one of the following:
2019-07-31 22:56:46 +05:30
2019-12-21 20:55:43 +05:30
- **Fixed**: Enter a fixed value.
2020-03-13 15:44:24 +05:30
- **From milestones**: Inherit a dynamic value from the milestones currently assigned to the epic's issues.
Note that GitLab 12.5 replaced this option with **Inherited** .
2020-06-23 00:09:42 +05:30
- **Inherited**: Inherit a dynamic value from the epic's issues, child epics, and milestones ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones** ).
2020-03-13 15:44:24 +05:30
### From milestones
2019-12-26 22:10:19 +05:30
2020-06-23 00:09:42 +05:30
> [Replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 by **Inherited**.
2019-07-31 22:56:46 +05:30
2019-12-26 22:10:19 +05:30
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.
2019-07-31 22:56:46 +05:30
2019-12-26 22:10:19 +05:30
These are dynamic dates which are recalculated if any of the following occur:
2019-07-31 22:56:46 +05:30
2019-12-21 20:55:43 +05:30
- Milestones are re-assigned to the issues.
- Milestone dates change.
- Issues are added or removed from the epic.
2019-07-31 22:56:46 +05:30
2019-12-26 22:10:19 +05:30
### Inherited
2020-06-23 00:09:42 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**.
2020-03-13 15:44:24 +05:30
2020-04-08 14:13:33 +05:30
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.
- **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.
2019-12-26 22:10:19 +05:30
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
2019-12-21 20:55:43 +05:30
2020-06-23 00:09:42 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7327) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.10.
2019-07-31 22:56:46 +05:30
2020-03-13 15:44:24 +05:30
If your epic contains one or more [child epics ](#multi-level-child-epics-ultimate ) which
2019-12-21 20:55:43 +05:30
have a [start or due date ](#start-date-and-due-date ), a
[roadmap ](../roadmap/index.md ) view of the child epics is listed under the parent epic.
2019-07-31 22:56:46 +05:30
2020-04-08 14:13:33 +05:30
2019-07-31 22:56:46 +05:30
## 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.
2020-04-08 14:13:33 +05:30
You can also consult the [group permissions table ](../../permissions.md#group-members-permissions ).
2019-07-31 22:56:46 +05:30
## Thread
- Comments: collaborate on that epic by posting comments in its thread.
2019-09-30 21:07:59 +05:30
These text fields also fully support
[GitLab Flavored Markdown ](../../markdown.md#gitlab-flavored-markdown-gfm ).
2019-07-31 22:56:46 +05:30
2020-04-08 14:13:33 +05:30
## Comment or start a thread
2019-07-31 22:56:46 +05:30
2020-04-08 14:13:33 +05:30
Once you write your comment, you can either:
2019-07-31 22:56:46 +05:30
2020-04-08 14:13:33 +05:30
- Click **Comment** , and your comment will be published.
- Click **Start thread** , and you will start a thread within that epic's discussion.
2019-07-31 22:56:46 +05:30
## Award emoji
2020-04-08 14:13:33 +05:30
You can [award an emoji ](../../award_emojis.md ) to that epic or its comments.
2019-07-31 22:56:46 +05:30
2019-09-30 21:07:59 +05:30
## Notifications
2019-07-31 22:56:46 +05:30
2020-04-08 14:13:33 +05:30
You can [turn on notifications ](../../profile/notifications.md ) to be alerted about epic events.
2019-09-04 21:01:54 +05:30
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X` .
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
