Context & History of GitHub Sub‑Issues

Issues have been the core of project coordination on GitHub since the platform launched. Over the years, teams added labels, milestones, and task lists to make tracking more precise. As codebases grew and cross‑repo work became common, a single flat list of tasks proved limiting. Users needed a way to break large objectives into smaller, linked pieces without leaving the issue view. This gap led to the concept of sub‑issues—a built‑in method for nesting tasks, keeping dependencies visible, and maintaining a clean workflow.

Implementation & Best Practices

To bring sub‑issues to life we followed a clear roadmap: first we defined the data model, then we extended the GraphQL API, next we updated the React components, and finally we ran internal dogfooding cycles before public release. This staged approach helped us catch regressions early and align the new UI with existing accessibility standards.

Data Modeling

We introduced a dedicated table that stores parent‑child relationships between issues. Each row links a parent issue ID to a child issue ID, allowing the system to compute progress efficiently. Aggregated progress is stored in a separate summary table, so rendering a parent’s completion status does not require recursive queries.

API Extensions

New fields were added to the GraphQL schema to expose sub‑issue links, progress percentages, and repository context. These fields let the front‑end request only the data it needs, reducing payload size. Our design mirrors patterns described in multi‑agent systems, where hierarchical relationships drive coordinated behavior.

Front‑End Integration

The existing list‑view component was enhanced to render nested items with expand/collapse controls. Keyboard navigation and screen‑reader labels were added in partnership with the accessibility team. Users can create a sub‑issue directly from the parent’s UI, edit titles, or move items between levels without page reloads.

Testing & Rollout

We leveraged internal projects to test sub‑issues on real roadmaps, collecting feedback on performance and usability. The iterative rollout was guided by insights from AI adoption in business, emphasizing early adopter feedback and rapid iteration.

Best Practices for Teams

• Start with a clear hierarchy: Define parent goals first, then break them into actionable child tasks.
• Keep titles concise: Short, descriptive titles make nested lists easier to scan.
• Use metadata wisely: Add issue numbers and repository names only when cross‑repo work is involved.
• Leverage filters: Apply has:sub‑issues‑progress and has:parent‑issue to monitor overall health.
• Review regularly: Treat sub‑issues as living documents; update status as work progresses.

By following these steps, teams can adopt sub‑issues smoothly, gain clearer visibility into complex work, and reduce the overhead of managing separate issue trackers.