What sub-issues add to GitHub Issues
Sub-issues let you split a larger issue into smaller, trackable tasks while keeping a parent-child hierarchy inside the Issues experience. Each sub-issue remains a first-class issue, so teams can assign work, link pull requests, and monitor progress without flattening everything into a single checklist. The structure is useful when a batch of work spans multiple repositories or needs several distinct steps; reporting progress per sub-issue keeps linked PRs smaller and reviews more focused.
Behind the scenes, completion state rolls upward automatically. Closing a child item updates the parent’s progress without a manual scan of the whole list, so large hierarchies stay easy to read at a glance.
Designing the hierarchy
Rather than extending the existing task list format, the team introduced a dedicated relationship model. A sub-issues table records each parent-child link between two issues. If Issue X is the parent of Issue Y, that relationship is stored directly, which keeps the hierarchy explicit and avoids encoding structure inside issue bodies.
Progress data is kept separate in a rollup table. This means the UI can fetch completion status for a list of sub-issues without traversing every node at request time. When a child issue is closed, the parent’s progress counter updates as a result of that state change.
The relationship model is stored in MySQL, a choice that also made it simpler to support sub-issues in GitHub Enterprise Server and GitHub Enterprise Cloud with data residency. For clients, the feature is exposed through GraphQL endpoints, which pairs with the newer Issues experience and its React-based list-view components. Reusing that shared UI code let the team build the feature faster while keeping interaction patterns consistent across Issues.
Refining through early use
GitHub ran sub-issues through internal dogfooding across several teams before wider release. Managing real projects exposed both strengths and rough edges. One example: the initial sub-issue list showed only titles, but beta testing showed that users needed more context. The final UI adds the issue number and, for cross-repository items, the repository name.
Using the feature to plan the sub-issues work itself also shaped search. The has:sub-issues-progress and has:parent-issue filters came directly out of early internal discussions around the right filtering syntax. Feedback from beta testers and hands-on use guided decisions about how much metadata to surface and how queries should behave, both of which were factors in making the feature feel polished rather than merely functional.
Built on the existing Issues foundation
Sub-issues sit cleanly on top of the existing Issues data model and GraphQL API. That integration means the feature works with the list views and components already used across Issues, and it keeps the door open for future enhancements without forking the interface.
Design and accessibility work went into the editing and management controls as well, with input from GitHub’s shared components team that built the list view. The focus throughout was to let teams break down tasks and track dependencies without leaving the flow of their existing work or learning a separate project-management surface.
