GitHub sub-issues: how to add them and the limits

GitHub sub-issues are issues linked under a parent issue so you can track a larger piece of work through its children. A parent can have up to 100 sub-issues, nested up to eight levels deep. Use a checklist for steps within one task, and give work its own issue when it needs independent ownership or discussion.

Should I use a checklist, a sub-issue or a separate issue?

Use a checklist for instructions inside an issue, a sub-issue for separately tracked work within a parent, and a separate issue for work with no meaningful parent. The useful question is whether a task needs its own record, not how many minutes it will take.

These are decision examples, not GitHub requirements. A ten-minute change may deserve an issue if another person must review it. A long investigation may remain one issue if splitting it would scatter the reasoning. Pick the smallest structure that makes ownership and completion clear.

A developer's workflow question illustrates the uncertainty about where to draw the line. It is one person's process question, not evidence that GitHub lacks child issues. GitHub already supplies the relationship. Gitsu helps manage the hierarchy you choose; it does not choose the decomposition for you.

How do I write a checklist in GitHub?

Put Markdown task items in an issue body or comment, using - [ ] for an unchecked step and - [x] for a completed step.

- [ ] Reproduce the export failure
- [ ] Add a regression test
- [x] Record the affected version

1. Open the issue on GitHub and edit its description, or write a comment.
2. Add each step on its own line using the task syntax.
3. Save the text, then use the rendered checkboxes to record completion.

Plain Markdown checklists are different from GitHub's retired tasklist blocks. The retirement does not mean every checkbox needs converting into a sub-issue. Keep the checklist where the individual steps do not need their own issue records.

If the export investigation uncovers work for a second owner, create an issue for that part and attach it as a sub-issue. Write the original checklist as acceptance steps for the parent rather than manually maintaining a second copy of each child's status. That keeps the parent useful as an explanation of the outcome.

How do I add a sub-issue to a parent issue?

Open the parent issue and choose Create sub-issue below its description.

1. Open the issue that should become the parent.
2. At the bottom of its description, click Create sub-issue.
3. Type the sub-issue's title. Optionally add a description and set the issue type, assignees, labels, projects and milestone.
4. To add several in a row, select Create more sub-issues.
5. Click Create.

To attach an issue that already exists, click the dropdown next to Create sub-issue, choose Add existing issue, and pick from the suggestions or search by title or number. Switch the repository in the picker to attach an issue from another repository.

The GitHub CLI does the same from a terminal:

• Create a new sub-issue: gh issue create --title "TITLE" --body "ISSUE-DESCRIPTION" --parent PARENT-ISSUE-NUMBER. The parent can be an issue number or URL.
• Attach existing issues: gh issue edit PARENT-ISSUE-NUMBER --add-sub-issue SUB-ISSUE-NUMBER. The flag takes a comma-separated list.
• Detach from the parent's side: gh issue edit PARENT-ISSUE-NUMBER --remove-sub-issue SUB-ISSUE-NUMBER.
• Detach from the child's side: gh issue edit SUB-ISSUE-NUMBER --remove-parent.

gh issue view ISSUE-NUMBER prints the parent and a "Sub-issues" section with each child's state and the completion count.

What are the limits on sub-issues?

A parent can hold up to 100 sub-issues, and sub-issues can nest up to eight levels deep. An issue has one parent at most. Sub-issues can come from other repositories, so an epic in one repository can own work in several.

Plan the hierarchy with the 100 limit in mind. An epic that needs more than 100 pieces of work is better split into child epics, each with its own sub-issues, which the eight levels allow.

How do I group by parent issue and show sub-issue progress in GitHub Projects?

Enable the Parent issue and Sub-issue progress fields to show relationships and completion in a GitHub Projects table.

1. In a table view, click + in the rightmost field header.
2. Under "Hidden fields", click Parent issue.
3. Repeat and click Sub-issue progress.

Parent issue names each item's parent. Group a view by it (View → Group by → Parent issue) to see each epic with its children underneath. Sub-issue progress shows how many of an item's sub-issues are complete.

To filter to the children of one issue, type parent-issue: and choose the issue from the list, or type it in full as parent-issue:"octocat/game#4", with your own owner, repository and issue number.

Use GitHub's project workflow settings to configure automatic additions to the project. Check project membership separately from the parent relationship: attaching a child to a parent and showing that child on a board answer different questions.

How do I manage sub-issues with the GraphQL API?

Use addSubIssue, removeSubIssue and reprioritizeSubIssue to attach, detach and order child issues. The mutations identify issues by node ID, not by number; addSubIssue also accepts the child's URL as subIssueUrl.

The first operation below adds a child, and the second reads an issue's tree through parent, subIssues and subIssuesSummary:

mutation AddSubIssue($input: AddSubIssueInput!) {
  addSubIssue(input: $input) {
    issue {
      id
    }
    subIssue {
      id
    }
  }
}

query IssueTree($owner: String!, $name: String!, $number: Int!) {
  repository(owner: $owner, name: $name) {
    issue(number: $number) {
      parent {
        number
        title
      }
      subIssuesSummary {
        total
        completed
        percentCompleted
      }
      subIssues(first: 100) {
        nodes {
          number
          title
          state
        }
      }
    }
  }
}

Send the mutation with {"input": {"issueId": "PARENT_NODE_ID", "subIssueId": "CHILD_NODE_ID"}}. If the child already has a parent, the call is refused unless the input also carries "replaceParent": true, which moves the child to the new parent. In the query, first: 100 matches the per-parent limit, so one page returns every child.

How does Gitsu handle sub-issues?

Gitsu reads and writes sub-issues through the same mutations, and shows the tree in an item's detail view.

In the Sub-issues section of an issue:

• Create sub-issue makes a new child. Type a title, and choose Add details to write a description.
• Link issue attaches an existing issue. The picker lists the board's own issues first, can switch to another repository, and accepts a pasted issue URL or a #number.
• Each child can be unlinked or dragged to a new position, which sends removeSubIssue or reprioritizeSubIssue.
• The header shows a count such as "3/5 completed".

Every change shows at once and is sent to GitHub in the background. If GitHub refuses it, Gitsu puts the list back and says what failed.

From the child's side, the detail view shows Sub-issue of with the parent and its progress, and Add parent searches issues or accepts a pasted issue URL. If the issue already has a parent, Gitsu asks before moving it and names the parent that will lose it. Only after you confirm does it send replaceParent: true, so an ordinary link never takes a child from another epic without asking.

In lists and filters:

• Rows show sub-issue progress, such as "2 of 5 sub-issues done".
• The filter menu has Has parent issue and Has sub-issue toggles.
• The filter box accepts parent-issue:octocat/game#4, and no:parent-issue hides sub-issues from any view.

On a timeline, Gitsu's Roadmap layout groups sub-issues under their parent and can show each parent's sub-issue progress on its bar; the roadmap view guide covers it. Configure project automations on GitHub and review which children actually appear on the board. The filter syntax guide lists the other qualifiers that combine with parent-issue:, and the getting-started guide connects your first project.

The image shows Gitsu's project interface, not the Sub-issues editor. The controls described above were checked against source; this image is not a live demonstration of creating a child issue.

What should I check before using Gitsu for an epic?

Check project size, permissions and how child issues reach the board before treating a parent as a complete project view. Gitsu shows one selected project at a time and loads up to 2,000 project items. A relationship between two GitHub issues does not remove that loading limit.

GitHub remains responsible for permissions and the parent relationship. Use GitHub to configure project automations. The free Gitsu Web App supports board work; the macOS app and agents require a paid Seat. See pricing for the current plans.

Open the parent issue in Gitsu, choose Create sub-issue for a new child or Link issue for an existing one, then arrange the child list in the order you want to review it. That puts hierarchy editing beside the project you already use while keeping the underlying issues available to teammates on GitHub.