Adding sub-issues

Learn about using sub-issues to break down your work into tasks.

Who can use this feature?

People with at least triage permissions for a repository can add sub-issues.

In this article

Note

Issue types, sub-issues, and advanced issue search are currently in an opt-in beta for organizations. To learn more and add your organization to the waitlist, see the "GitHub Blog."

You can add sub-issues to an issue to break down larger pieces of work into tasks. Your sub-issues show their relationship to the parent issue allowing you to track your work across GitHub. Parent issues and sub-issue progress is also available in your projects, allowing you to build views, filter, and group by parent issue.

Your sub-issues can themselves contain sub-issues, allowing you to create full hierarchies of issues that visualize entire projects or pieces of work and show the relationships between your issues.

You can add up to fifty sub-issues per parent issue and create up to eight levels of nested sub-issues.

Creating a sub-issue

  1. Navigate to the issue that you want to add a sub-issue to.
  2. At the bottom of the issue description, click Create sub-issue.
  3. In the dialog, type the title for your sub-issue.
  4. Optionally, type the description for your issue, and set the issue type and any assignees, labels, projects, and milestones.
  5. Optionally, if you want to continue create sub-issues for this parent issue, select Create more sub-issues.
  6. Click Create.

Adding an existing issue as a sub-issue

  1. Navigate to the issue that you want to add a sub-issue to.

  2. At the bottom of the issue description, next to "Create sub-issue", click .

    Screenshot of the sub-issues section below the issue description. The "View more sub-issue options" button is highlighted with an orange rectangle.

  3. In the drop-down menu, click Add existing issue.

  4. Select the issue that you want to add as a sub-issue.

    • Select an issue from one of the suggestions.
    • In the "Search issues" field, type an issue title or issue number, then click on the results.
    • To add issues from other repositories, click next to the repository name and select a different repository.