Parent and Sub-Issues

Use sub-issues to break down larger "parent" issues into smaller pieces of work.

Overview

Consider creating sub-issues when a set of work is too large to be a single issue but too small to be a project. Sub-issues also ideal for splitting up work shared across teammates. When you add a sub-issue to another issue, the other issue becomes its "parent".

Create a sub-issue

Create a sub-issue by opening the parent issue and click the + Add sub-issues button below the issue description. This will launch the sub-issue editor. You can also use the shortcut Command Shift O to open the editor.

You can also create sub-issues in the issue creation modal (C) by pressing Command Shift O to open the editor or under the ... menu and "Add sub-issue".

When you save a sub-issue, it will automatically launch the editor to create a new one. If you want to create a new one with the same values (labels/assignee etc.) you can press ⌘ Shift Enter or Shift+ click the save button. Press Esc to exit the sub-issue editor and continue updating the parent issue.

You can turn a comment under an issue into a sub-issue by hovering over a comment and clicking the … menu then "new sub-issue from comment". Selecting a comment's text and pressing ⌘ Shift O will also create a sub-issue.

If you have a list (bulleted, numbered or checklist) you can highlight the checklist and hit ⌘ Shift O to convert to sub-issues or choose the "Create sub-issues(s) from selection" item in the formatting toolbar.

You can add a template using the templates icon when creating a sub-issue or using the command menu under "Create new sub-issue from template" when viewing the parent.

Copy properties

Sub-issues created in the editor automatically copy issue properties from the parent issue such as the project and cycle as long as those are set before you create the sub-issue.

Team, labels and assignees are not copied over. You can't create sub-issues while editing the parent issue, but the option will come up once you press save.

You can duplicate a parent and its sub-issues from the Parent's ... menu under "Duplicate" and hit the toggle "Include sub-issues".

Status automation

Optionally, configure the following behaviors at the team level (Settings > Team > Workflow) to automate status relations between parent and sub-issues. Status changes triggered by Git integrations will also respect these automations.

Parent auto-close

When all sub-issues are marked as done, the parent issue will also be marked as done automatically.

Sub-issue auto-close

When the parent issue is marked as done, all remaining sub-issues will also be marked as done.

Converting issues

Turn issues into sub-issues

Turn an existing issue(s) into sub-issues of another issue by selecting one or multiple issues and then taking the action to set the parent issue. This action is accessible from the command menu or by pressing Cmd Shift P and selecting a parent issue.

Turn issues into parent issues

To make an existing issue a parent issue of another issue, hover over a sub-issue and take the action "Set Parent" in the contextual menu, command menu or ... menu.

Turn sub-issues into issues

You can turn a sub-issue into a regular issue again using the ⌘/ctrlK menu option "Remove parent".

Turn issues into projects

Sometimes an issue grows so large it's more appropriate to turn it into a project instead. To do so, hover over the parent's ... menu and choose "Convert to project." The project will inherit its details from the original parent issue, and former sub-issues will become standard issues in the project.

Filter sub-issues

You can usually set the view to show or hide sub-issues in Display Options. You can also use Filters to show only top-level (parent) issues, issues with sub-issues, or only sub-issues. If you use these filters frequently, consider creating a custom view.

You can also hide completed sub-issues by default under the ... menu and toggling "Always hide completed sub-issues".

You can also sort your sub-issues under an issue from the … menu and "Order by" though this only updates it for the current user, not globally.

Navigate between issues

Navigate between a parent issue and its sub-issues by using the menu pictured.