@@ -8,57 +8,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Epics **(PREMIUM)**
> - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.2.
> - Single-level Epics [were moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8.
> - Single-level epics [were moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8.
Epics let you manage your portfolio of projects more efficiently by tracking groups of [issues](../../project/issues/index.md)
that share a theme across projects and milestones.
When [issues](../../project/issues/index.md) share a theme across projects and milestones,
you can manage them by using epics.
An epic's page contains the following tabs:
You can also create child epics, and assign start and end dates,
which creates a visual roadmap for you to view progress.
-**Issues**: issues added to this epic.
-**Epics and Issues**: epics and issues added to this epic.
Appears instead of the **Issues** tab if you have access to [multi-level epics](#multi-level-child-epics).
Child epics and their issues are shown in a tree view.
Use epics:
- To reveal the child epics and issues, select the chevron (**>**) next to a parent epic.
- To see a breakdown of open and closed items, hover over the total counts.
The number provided here includes all epics associated with this project. The number includes
epics for which users may not yet have permission.
-[**Roadmap**](#roadmap-in-epics): a roadmap view of child epics which have start and due dates.
Appears if you have access to [multi-level epics](#multi-level-child-epics).
## 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.
- Track when the work for the group of issues is targeted to begin, and when it's targeted to end.
- Discuss and collaborate on feature ideas and scope at a high level.
## Manage epics
To learn what you can do with an epic, see [Manage epics](manage_epics.md). Possible actions include:
- When your team is working on a large feature that involves multiple discussions
in different issues in different projects in a [group](../index.md).
- To track when the work for the group of issues is targeted to begin and end.
- To discuss and collaborate on feature ideas and scope at a high level.
## Relationships between epics and issues
The possible relationships between epics and issues are:
- 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)**
- An epic is the parent of one or more child epics. For details see [Multi-level child epics](manage_epics.md#multi-level-child-epics).
```mermaid
graph TD
...
...
@@ -67,72 +37,13 @@ graph TD
Child_epic --> Issue2
```
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 an issue between epics
- Promote an issue to an epic
## 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.
> - The health status of a closed issue [is hidden](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3 or later.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7.
Report or respond to the health of issues and epics by setting a red, amber, or green [health status](../../project/issues/managing_issues.md#health-status), which then appears on your Epic tree.
## Multi-level child epics **(ULTIMATE)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8333) in GitLab Ultimate 11.7.
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 **Epics and Issues** tab.
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 seven levels deep.
See [Manage multi-level child epics](manage_epics.md#manage-multi-level-child-epics) for
steps to create, move, reorder, or delete child epics.
## 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.
-**Inherited**: inherit a dynamic value from the epic's issues, child epics, and milestones.
### Inherited
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**.
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 found start date or milestone.
- For the **due date**: GitLab sets 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.
The parent epic's start date then reflects this change and propagates upwards to the top epic.
## Roadmap in epics **(ULTIMATE)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7327) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.10.
If your epic contains one or more [child epics](#multi-level-child-epics) which
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.
If your epic contains one or more [child epics](manage_epics.md#multi-level-child-epics) that
have a start or due date, a visual
[roadmap](../roadmap/index.md) of the child epics is listed under the parent epic.
1. Select **Create epic**. You are taken to view the newly created epic.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**.
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 found start date or milestone.
- For the **due date**: GitLab sets 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.
The parent epic's start date then reflects this change and propagates upwards to the top epic.
## Edit an epic
...
...
@@ -55,7 +73,7 @@ To edit an epic's title or description:
1. Make your changes.
1. Select **Save changes**.
To edit an epics' start date, due date, or labels:
To edit an epic's start date, due date, or labels:
1. Select **Edit** next to each section in the epic sidebar.
1. Select the dates or labels for your epic.
...
...
@@ -151,6 +169,19 @@ The sort option and order is saved and used wherever you browse epics, including
## Change activity sort order
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214364) in [GitLab Premium](https://about.gitlab.com/pricing/) 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, click the **Oldest first** dropdown menu and select either oldest
or newest items to be shown first.
## Make an epic confidential
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213068) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0 behind a feature flag, disabled by default.
...
...
@@ -200,6 +231,13 @@ To add a new issue to an epic:
If there are multiple issues to be added, press <kbd>Space</kbd> and repeat this step.
1. Select **Add**.
#### View count of issues in an epic
On the **Epics and Issues** tab, 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.
#### Create an issue from an epic
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5419) in GitLab 12.7.
...
...
@@ -286,9 +324,16 @@ 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](https://about.gitlab.com/handbook/marketing/strategic-marketing/getting-started/104/).
## Manage multi-level child epics **(ULTIMATE)**
## Multi-level child epics **(ULTIMATE)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8333) in GitLab Ultimate 11.7.
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 **Epics and Issues** tab.
When you add an epic that's already linked to a parent epic, the link to its current parent is removed.
With [multi-level epics](index.md#multi-level-child-epics), you can manage more complex projects.
Epics can contain multiple nested child epics, up to a total of seven levels deep.
