1--- 2type: howto 3stage: Plan 4group: Product Planning 5info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments 6--- 7 8# Manage epics **(PREMIUM)** 9 10This page collects instructions for all the things you can do with [epics](index.md) or in relation 11to them. 12 13## Create an epic 14 15> - The New Epic form [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211533) in GitLab 13.2. 16> - In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/229621) and later, the New Epic button on the Epics list opens the New Epic form. 17> - In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45948) and later, you can create a new epic from an empty roadmap. 18 19To create an epic in the group you're in: 20 211. Get to the New Epic form: 22 - Go to your group and from the left sidebar select **Epics**. Then select **New epic**. 23 - From an epic in your group, select **New epic**. 24 - From anywhere, in the top menu, select **New...** (**{plus-square}**) **> New epic**. 25 - In an empty [roadmap](../roadmap/index.md), select **New epic**. 26 271. Enter a title. 281. Complete the fields. 29 - Enter a description. 30 - To [make the epic confidential](#make-an-epic-confidential), select the checkbox under **Confidentiality**. 31 - Choose labels. 32 - Select a start and due date, or [inherit](#start-and-due-date-inheritance) them. 331. Select **Create epic**. 34 35The newly created epic opens. 36 37### Start and due date inheritance 38 39> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**. 40 41If you select **Inherited**: 42 43- For the **start date**: GitLab scans all child epics and issues assigned to the epic, 44 and sets the start date to match the earliest start date found in the child epics or the milestone 45 assigned to the issues. 46- For the **due date**: GitLab scans all child epics and issues assigned to the epic, 47 and sets the due date to match the latest due date found in the child epics or the milestone 48 assigned to the issues. 49 50These are dynamic dates and recalculated if any of the following occur: 51 52- A child epic's dates change. 53- Milestones are reassigned to an issue. 54- A milestone's dates change. 55- Issues are added to, or removed from, the epic. 56 57Because the epic's dates can inherit dates from its children, the start date and due date propagate from the bottom to the top. 58If the start date of a child epic on the lowest level changes, that becomes the earliest possible start date for its parent epic. 59The parent epic's start date then reflects this change and propagates upwards to the top epic. 60 61## Edit an epic 62 63After you create an epic, you can edit the following details: 64 65- Title 66- Description 67- Start date 68- Due date 69- Labels 70 71To edit an epic's title or description: 72 731. Select **Edit title and description** **{pencil}**. 741. Make your changes. 751. Select **Save changes**. 76 77To edit an epic's start date, due date, or labels: 78 791. Next to each section in the right sidebar, select **Edit**. 801. Select the dates or labels for your epic. 81 82## Bulk edit epics 83 84> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7250) in GitLab 12.2. 85 86Users with at least the [Reporter role](../../permissions.md) can manage epics. 87 88When bulk editing epics in a group, you can edit their labels. 89 90To update multiple epics at the same time: 91 921. In a group, go to **Epics > List**. 931. Select **Edit epics**. A sidebar on the right appears with editable fields. 941. Select the checkboxes next to each epic you want to edit. 951. Select the appropriate fields and their values from the sidebar. 961. Select **Update all**. 97 98## Delete an epic 99 100NOTE: 101To delete an epic, you must be an [Owner](../../permissions.md#group-members-permissions) of a group 102or subgroup. 103 104To delete the epic: 105 1061. Select **Edit title and description** **{pencil}**. 1071. Select **Delete**. A modal appears to confirm your action. 108 109Deleting an epic releases all existing issues from their associated epic in the system. 110 111WARNING: 112If you delete an epic, all its child epics and their descendants are deleted as well. If needed, you can [remove child epics](#remove-a-child-epic-from-a-parent-epic) from the parent epic before you delete it. 113 114## Close an epic 115 116Whenever you decide that there is no longer need for that epic, 117close the epic by: 118 119- Selecting **Close epic**. 120 121 ![close epic - button](img/button_close_epic.png) 122 123- Using the `/close` [quick action](../../project/quick_actions.md). 124 125## Reopen a closed epic 126 127You can reopen an epic that was closed by: 128 129- Selecting **Reopen epic**. 130 131 ![reopen epic - button](img/button_reopen_epic.png) 132 133- Using the `/reopen` [quick action](../../project/quick_actions.md). 134 135## Go to an epic from an issue 136 137If an issue belongs to an epic, you can go to the parent epic with the 138link in the right sidebar. 139 140![containing epic](img/containing_epic.png) 141 142## View epics list 143 144In a group, the left sidebar displays the total count of open epics. 145This number indicates all epics associated with the group and its subgroups, including epics you 146might not have permission to view. 147 148To view epics in a group: 149 1501. On the top bar, select **Menu > Groups** and find your group. 1511. On the left sidebar, select **Epics**. 152 153### Cached epic count 154 155> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299540) in GitLab 13.11 [with a flag](../../../administration/feature_flags.md) named `cached_sidebar_open_epics_count`. Enabled by default. 156> - Enabled on self-managed and on GitLab.com in GitLab 14.0. [Feature flag `cached_sidebar_open_epics_count`](https://gitlab.com/gitlab-org/gitlab/-/issues/327320) removed. 157 158The total count of open epics displayed in the sidebar is cached if higher 159than 1000. The cached value is rounded to thousands or millions and updated every 24 hours. 160 161## Search for an epic from epics list page 162 163> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) from GitLab Ultimate to GitLab Premium in 12.8. 164> - Searching by the user's reaction emoji [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325630) in GitLab 13.11. 165> - Sorting by epic titles [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.1. 166 167You can search for an epic from the list of epics using filtered search bar based on following 168parameters: 169 170- Title or description 171- Author name / username 172- Labels 173- Reaction emoji 174 175![epics search](img/epics_search_v13_11.png) 176 177To search: 178 1791. On the top bar, select **Menu > Groups** and find your group. 1801. On the left sidebar, select **Epics**. 1811. Select the field **Search or filter results**. 1821. From the dropdown menu, select the scope or enter plain text to search by epic title or description. 1831. Press <kbd>Enter</kbd> on your keyboard. The list is filtered. 184 185You can also sort epics list by: 186 187- Created date 188- Last updated 189- Start date 190- Due date 191- Title 192 193Each option contains a button that can toggle the order between **Ascending** and **Descending**. 194The sort option and order is saved and used wherever you browse epics, including the 195[Roadmap](../roadmap/index.md). 196 197![epics sort](img/epics_sort.png) 198 199## Change activity sort order 200 201> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214364) in GitLab 13.2. 202 203You can reverse the default order and interact with the activity feed sorted by most recent items 204at the top. Your preference is saved via local storage and automatically applied to every epic and issue 205you view. 206 207To change the activity sort order, select the **Oldest first** dropdown menu and select either oldest 208or newest items to be shown first. 209 210![Issue activity sort order dropdown button](img/epic_activity_sort_order_v13_2.png) 211 212## Make an epic confidential 213 214> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213068) in GitLab 13.0 behind a feature flag, disabled by default. 215> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/224513) in GitLab 13.2. 216> - You can [use the Confidentiality option in the epic sidebar](https://gitlab.com/gitlab-org/gitlab/-/issues/197340) in GitLab 13.3 and later. 217 218If you're working on items that contain private information, you can make an epic confidential. 219 220NOTE: 221A confidential epic can only contain [confidential issues](../../project/issues/confidential_issues.md) 222and confidential child epics. However, merge requests are public, if created in a public project. 223Read [Merge requests for confidential issues](../../project/merge_requests/confidential.md) 224to learn how to create a confidential merge request. 225 226To make an epic confidential: 227 228- **When creating an epic:** select the checkbox under **Confidentiality**. 229- **In an existing epic:** on the right sidebar, select **Edit** next to **Confidentiality**, and then 230 select **Turn on**. 231 232## Manage issues assigned to an epic 233 234This section collects instructions for all the things you can do with [issues](../../project/issues/index.md) 235in relation to epics. 236 237### View count of issues in an epic 238 239On the **Epics and Issues** tab, under each epic name, hover over the total counts. 240 241The number indicates all epics associated with the project, including issues 242you might not have permission to. 243 244### Add a new issue to an epic 245 246You can add an existing issue to an epic, or create a new issue that's 247automatically added to the epic. 248 249#### Add an existing issue to an epic 250 251Existing issues that belong to a project in an epic's group, or any of the epic's 252subgroups, are eligible to be added to the epic. Newly added issues appear at the top of the list of 253issues in the **Epics and Issues** tab. 254 255An epic contains a list of issues and an issue can be associated with at most one epic. 256When you add a new issue that's already linked to an epic, the issue is automatically unlinked from its 257current parent. 258 259To add a new issue to an epic: 260 2611. On the epic's page, under **Epics and Issues**, select **Add**. 2621. Select **Add an existing issue**. 2631. Identify the issue to be added, using either of the following methods: 264 - Paste the link of the issue. 265 - Search for the desired issue by entering part of the issue's title, then selecting the desired 266 match ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9126) in GitLab 12.5). 267 268 If there are multiple issues to be added, press <kbd>Space</kbd> and repeat this step. 2691. Select **Add**. 270 271#### Create an issue from an epic 272 273> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5419) in GitLab 12.7. 274 275Creating an issue from an epic enables you to maintain focus on the broader context of the epic 276while dividing work into smaller parts. 277 278To create an issue from an epic: 279 2801. On the epic's page, under **Epics and Issues**, select **Add**. 2811. Select **Add a new issue**. 2821. Under **Title**, enter the title for the new issue. 2831. From the **Project** dropdown, select the project in which the issue should be created. 2841. Select **Create issue**. 285 286### Remove an issue from an epic 287 288You can remove issues from an epic when you're on the epic's details page. 289After you remove an issue from an epic, the issue is no longer associated with this epic. 290 291To remove an issue from an epic: 292 2931. Next to the issue you want to remove, select **Remove** (**{close}**). 294 The **Remove issue** warning appears. 2951. Select **Remove**. 296 297![List of issues assigned to an epic](img/issue_list_v13_1.png) 298 299### Reorder issues assigned to an epic 300 301> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9367) in GitLab 12.5. 302 303New issues appear at the top of the list in the **Epics and Issues** tab. 304You can reorder the list of issues by dragging them. 305 306To reorder issues assigned to an epic: 307 3081. Go to the **Epics and Issues** tab. 3091. Drag issues into the desired order. 310 311### Move issues between epics **(ULTIMATE)** 312 313> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in GitLab 13.0. 314 315New issues appear at the top of the list in the **Epics and Issues** 316tab. You can move issues from one epic to another. 317 318To move an issue to another epic: 319 3201. Go to the **Epics and Issues** tab. 3211. Drag issues into the desired parent epic. 322 323### Promote an issue to an epic 324 325> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in GitLab 11.6. 326> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) from GitLab Ultimate to GitLab Premium in 12.8. 327 328If you have the necessary [permissions](../../permissions.md) to close an issue and create an 329epic in the immediate parent group, you can promote an issue to an epic with the `/promote` 330[quick action](../../project/quick_actions.md#issues-merge-requests-and-epics). 331Only issues from projects that are in groups can be promoted. When you attempt to promote a confidential 332issue, a warning is displayed. Promoting a confidential issue to an epic makes all information 333related to the issue public as epics are public to group members. 334 335When an issue is promoted to an epic: 336 337- An epic is created in the same group as the project of the issue. 338- Subscribers of the issue are notified that the epic was created. 339 340The following issue metadata is copied to the epic: 341 342- Title, description, activity/comment thread. 343- Upvotes/downvotes. 344- Participants. 345- Group labels that the issue already has. 346- Parent epic. 347 348### Use an epic template for repeating issues 349 350You can create a spreadsheet template to manage a pattern of consistently repeating issues. 351 352<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> 353For an introduction to epic templates, see [GitLab Epics and Epic Template Tip](https://www.youtube.com/watch?v=D74xKFNw8vg). 354 355For more on epic templates, see [Epic Templates - Repeatable sets of issues](https://about.gitlab.com/handbook/marketing/strategic-marketing/getting-started/104/). 356 357## Multi-level child epics **(ULTIMATE)** 358 359You can add any epic that belongs to a group or subgroup of the parent epic's group. 360New child epics appear at the top of the list of epics in the **Epics and Issues** tab. 361 362When you add an epic that's already linked to a parent epic, the link to its current parent is removed. 363 364Epics can contain multiple nested child epics, up to a total of seven levels deep. 365 366### Add a child epic to an epic 367 368To add a child epic to an epic: 369 3701. Select **Add**. 3711. Select **Add a new epic**. 3721. Identify the epic to be added, using either of the following methods: 373 - Paste the link of the epic. 374 - Search for the desired issue by entering part of the epic's title, then selecting the desired 375 match ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9126) in GitLab 12.5). 376 377 If there are multiple epics to be added, press <kbd>Space</kbd> and repeat this step. 3781. Select **Add**. 379 380### Move child epics between epics 381 382> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in GitLab 13.0. 383 384New child epics appear at the top of the list in the **Epics and Issues** tab. 385You can move child epics from one epic to another. 386When you add a new epic that's already linked to a parent epic, the link to its current parent is removed. 387Issues and child epics cannot be intermingled. 388 389To move child epics to another epic: 390 3911. Go to the **Epics and Issues** tab. 3921. Drag epics into the desired parent epic. 393 394### Reorder child epics assigned to an epic 395 396> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9367) in GitLab 12.5. 397 398New child epics appear at the top of the list in the **Epics and Issues** tab. 399You can reorder the list of child epics. 400 401To reorder child epics assigned to an epic: 402 4031. Go to the **Epics and Issues** tab. 4041. Drag epics into the desired order. 405 406### Remove a child epic from a parent epic 407 408To remove a child epic from a parent epic: 409 4101. Select **Remove** (**{close}**) in the parent epic's list of epics. 411 The **Remove epic** warning appears. 4121. Select **Remove**. 413