What a sub-issue actually is
Every tracker eventually gets that one issue.
It has five different asks buried in the description, three people commenting about unrelated things, and nobody sure what “done” means.
The obvious fix is to split it into sub-issues.
But splitting too early, or too eagerly, creates its own mess: a parent nobody closes, children nobody owns, and overhead that outweighs the clarity you were chasing.
This guide walks through the decision.
You will learn the signals that a task genuinely needs breaking down.
You will also learn when a single issue serves you better.
Finally, you will see how to structure sub-issues so they help you track progress.
A sub-issue is a normal issue with a recorded relationship to a parent.
On GitHub, you can add sub-issues to an issue to break larger work into tasks.
Sub-issues show their relationship to the parent, so you can track work across the platform.
Parent and sub-issue progress is also available in projects, where you can build views, filter, and group by parent issue.
Sub-issues can themselves contain sub-issues, so you can build hierarchies that visualize an entire piece of work.
GitHub documents a limit of up to 100 sub-issues per parent and up to eight levels of nesting, which tells you the feature is built for serious structure, not just tidy lists.
The key point: the relationship is visible and machine-readable.
That is what separates sub-issues from simply writing “part 1, part 2” in a description.
Because the link exists, tools can roll up progress and you can filter on it.
Signals that an issue should be split
Use these checks before you create anything.
If several are true, splitting will probably pay off.
- Different finish lines. The issue describes work that could ship or be reviewed at different times. If one part can be done this week and another depends on something outside your control, they belong in separate issues.
- Different owners. Two people cannot both “own” one issue cleanly. If design, build, and launch each have a different natural owner, sub-issues make responsibility explicit.
- Comments are drifting. When discussion about one aspect buries updates about another, contributors stop reading the thread. Separate issues give each conversation a home.
- The description needs a checklist longer than a few items. A short checklist inside one issue is fine. When the list itself has dependencies and ordering, those items are tasks, not notes.