doc/user/work_items/child_items.md
{{< details >}}
{{< /details >}}
Child items are work items that are nested under a parent work item. This creates a hierarchy for organizing and tracking work.
Child items can be:
Parent epic
|─ Child epic
|─ Issue
|- Task
|─ Issue
|- Task
|─ Issue
You can use child items to solve several planning and coordination challenges.
The following examples show how child items help teams work together more effectively.
In the Child items section, you can see epics, issues, and tasks assigned to an epic.
You can also see any epics, issues, and tasks inherited by descendant items.
Only epics, issues, and tasks that you can access show on the list.
You can view issues assigned to an epic if they are in the group’s child project. This is because a project's visibility setting must be the same as, or less restrictive than, its parent group.
You can track the progress of work items using different criteria.
In the Child items section header of an epic, the number of descendant work items and their total weight is displayed. Task weights are included in the total issue weight.
To see the number of open and closed work items, in the section header or under each epic name, hover over the total counts.
The numbers reflect all child work items associated with the epic, including those you might not have permission to view.
{{< history >}}
{{< /history >}}
In the Child items section header of an epic, the epic progress percentage is displayed.
To see the completed and total weight of child items, in the section header, hover over the percentage.
Tasks are included in the progress percentage as part of the child issue percentage.
The weights and progress reflect all issues associated with the epic, including issues you might not have permission to view.
You can:
{{< history >}}
{{< /history >}}
Add an existing issue to an epic, or create a new issue that's automatically added to the epic.
The maximum number of direct child issues and epics is 5000.
You can add existing issues to an epic, including issues in a project from a different group hierarchy.
Newly added issues appear at the top of the list of issues in the Child items section.
An epic contains a list of issues and an issue can be set as a child item of at most one epic. When you add a new issue that's already linked to an epic, the issue is automatically unlinked from its current parent.
Prerequisites:
To add an existing issue to an epic:
On the epic's page, under Child items, select Add.
Select Existing issue.
Identify the issue to be added, using either of the following methods:
If there are multiple issues to be added, press <kbd>Space</kbd> and repeat this step.
Select Add.
Creating an issue from an epic enables you to maintain focus on the broader context of the epic while dividing work into smaller parts.
You can create a new issue from an epic only in projects that are in the epic's group or one of its descendant subgroups. To create a new issue in a project that was shared with the epic's group, first create the issue directly in the project, and then add an existing issue to an epic.
Prerequisites:
To create an issue from an epic:
The new issue is assigned to the epic.
You can reorder child items and reorganize them within the hierarchy.
New issues show at the top of the list in the Child items section. You can reorder the list of issues by dragging them.
Prerequisites:
To reorder issues assigned to an epic:
{{< details >}}
{{< /details >}}
New issues appear at the top of the list in the Child items tab. You can move issues from one epic to another.
Prerequisites:
To move an issue to another epic:
{{< history >}}
move_issue_children. Disabled by default.move_issue_children removed.{{< /history >}}
When you move an issue to another project, all its child items are also moved to the target project and remain as child items of the moved issue. Each item is moved the same way as the parent, that is, it's closed in the original project and copied to the target project.
You can remove issues from an epic when you're on the epic's details page. After you remove an issue from an epic, the issue is no longer associated with this epic.
Prerequisites:
To remove an issue from an epic:
{{< details >}}
{{< /details >}}
Epics can contain multiple nested child epics. You can work with these multi-level child epics in the following ways:
Epics can contain multiple nested child epics, up to a total of 7 levels deep.
{{< history >}}
{{< /history >}}
To create a hierarchy of epics, add a parent epic to an existing epic. This helps organize and track related work across multiple epics.
Prerequisites:
To add a parent epic:
The parent epic is added.
Add a child epic that belongs to a group that is different from the parent epic's group.
Prerequisites:
To add a child epic from another group, paste the epic's URL when adding an existing epic.
From an epic, view its child epics and related milestones on the roadmap.
Prerequisites:
To view child epics from the parent:
Prerequisites:
To add a new epic as child epic:
To add an existing epic as child epic:
In an epic, in the Child items section, select Add > Existing epic.
Identify the epic to be added, using either of the following methods:
If there are multiple epics to be added, press <kbd>Space</kbd> and repeat this step.
Select Add.
New child epics appear at the top of the list in the Child items section. You can move child epics from one epic to another. When you add a new epic that's already linked to a parent epic, the link to its current parent is removed. Issues and child epics cannot be intermingled.
Prerequisites:
To move child epics to another epic:
New child epics appear at the top of the list in the Child items section. You can reorder the list of child epics.
Prerequisites:
To reorder child epics assigned to an epic:
Prerequisites:
To remove a child epic from a parent epic:
You can configure what information is displayed in the Child items section, so that you can focus on what matters most for your workflow.
{{< history >}}
{{< /history >}}
You can configure what information is displayed in the Child items section, so that you can focus on what matters most for your workflow.
[!note] When you change the information displayed in one epic or issue, you change it for all work items in your groups and projects.
At the top-right corner of the Child items section header, select Display options ({{< icon name="preferences" >}}).
By default, all options and fields are visible.
To change the displayed information, turn the following toggles on or off: