How to create a subtask in Jira (and link work items)

A subtask in Jira is a small piece of work that lives under a parent work item. You create one from the parent. Open the work item, add a child, give it a summary and save. The button you use depends on whether your project is company-managed or team-managed. The steps for both are below.

Atlassian now calls issues "work items" in Jira Cloud, so the buttons you see may say "work item" where older guides say "issue". Subtasks work the same way.

Create a subtask in a company-managed project

1. Open the parent work item. A subtask always needs a parent, so start there, not from the Create button in the top bar.
2. Under the summary, select Add or create related work.
3. Choose Create subtask.
4. Type a summary. Keep it to the one thing the subtask covers.
5. Select Create. Repeat for each piece of work you want to split out.

The new subtask copies part of the parent's context. Atlassian's docs say "a subtask will inherit the space, work security level, and sprint value (software spaces) from their parent". So you don't set the sprint on a subtask. It takes the story's sprint.

Source: Atlassian Support: Create a work item and a subtask

If you cannot find the option, subtasks are probably switched off. In company-managed projects, subtasks appear only when an admin has enabled them and added the subtask work type to the project's work type scheme. Only a Jira admin can change this, and you can't turn it on from the work item.

Create a subtask in a team-managed project

1. Open the work item that will be the parent.
2. Select Add, then Child work item.
3. Enter the summary and any description you need.
4. Select Create.

You can also add subtasks from the board. Set Group by to Subtask, then use the + button under the parent card. This lets you break down several stories without opening each one.

Team-managed projects have subtasks on by default. If the child option is missing, add it under Space settings, then Work types.

Source: Atlassian Support: Manage subtasks in team-managed projects

What subtasks cannot do

Three limits catch people out. Only the third has a setting, and only an admin can change it.

• No nesting. A subtask cannot have its own subtask. Child work items can only be created under standalone work items, so the tree stops at two levels below the epic: epic, then story, then subtask.
• No direct move between parents. You cannot drag a subtask to a different story. Convert it to a standalone work item first, then convert it back to a subtask under the new parent.
• An admin may have to enable the type. In company-managed projects, the subtask work type must be in the work type scheme. Until it is, the create option doesn't appear.

If a subtask needs children of its own, it is probably a story, and its parent is probably an epic.

Subtasks on the board

By default a board shows stories and bugs, not their subtasks. To see the breakdown, set Group by to Subtask. Each parent becomes a swimlane header and its subtasks become the cards inside that lane.

This helps in standups. The default view might show six stories in progress. Grouped by subtask, it shows which subtasks are moving and which parent is stuck because one subtask hasn't started. Switch back to see the whole sprint.

Subtasks share the parent's sprint, so moving a story to the next sprint moves its subtasks too.

Subtasks vs linked work items

Both connect two work items. A subtask is part of its parent. A link connects two separate work items.

Use a subtask when the work only makes sense inside the parent, belongs to the same team and ships in the same sprint. Use a link when the items are in different projects, belong to different teams or one has to finish before the other can start.

Link types

Your instance may show more types, such as causes, implements or reviews. Admins can add their own.

How to link two work items

1. Right-click the work item, or open it and use the ••• menu.
2. Select Link work item. Inside an open item you can also use Add, then Linked work item.
3. Pick the link type, then search for the target item by key or summary.
4. Select Link. Jira adds the reverse link to the other item.

Source: Atlassian Support: Link work items

Find subtasks and links with JQL

For other everyday searches, such as overdue issues, unassigned work or active sprints, try the free JQL query builder.

Once a project has a few hundred work items, clicking through parents takes too long. These four JQL queries cover most needs.

• parent = PROJ-123 finds every subtask of one parent.
• issuetype in subTaskIssueTypes() finds all subtasks, whatever they are called in your instance. The function returns every work type marked as a subtask type.
• issuetype not in subTaskIssueTypes() finds everything except subtasks. Use it in sprint reports, where subtasks would count the same work twice.
• issue in linkedIssues("PROJ-123", "blocks") finds the items that PROJ-123 blocks.

Combine them with the usual filters, for example issuetype in subTaskIssueTypes() AND assignee = currentUser() AND statusCategory != Done to see only your own open subtasks.

Source: Atlassian Support: JQL functions

If you run the same JQL often, save it as a filter. To run JQL outside the browser, see the Jira desktop app options. For the keys worth learning first, see Jira keyboard shortcuts.

Seeing the whole tree at once

Creating subtasks is easy. Keeping track of which epic and story each subtask belongs to, and what blocks what, is harder. Jira in a browser shows the children of one work item at a time.

If your team is considering a lighter tool for this reason, read Linear vs Jira. Which tracker you use and which app you read it in are separate choices.

Frequently asked questions