GitHub has launched sub-issues, a feature designed to simplify complex issue management and streamline workflows for project teams. Sub-issues enable users to break down larger issues into smaller, manageable pieces, fostering greater clarity, organization, and efficiency. This innovative feature is poised to transform how teams plan, track, and execute work on GitHub.

Sub-issues integrate seamlessly into the GitHub Issues experience, providing hierarchical lists within a single issue. From tracking dependencies to enabling detailed task breakdowns across repositories, sub-issues help users stay laser-focused on their objectives while maintaining visibility over progress.

What Are Sub-Issues?

Sub-issues are an enhancement to GitHub Issues that allow users to create hierarchical tasks within a given issue. This functionality is perfect for breaking down large, complex tasks into smaller, actionable items. Whether organizing cross-repository work or managing intricate dependencies, sub-issues provide the structure needed to handle even the most complex projects.

Example Use Case: Imagine you’re implementing code across multiple repositories. Breaking this batch of work into discrete sub-issues helps track progress seamlessly while keeping linked pull requests concise and easier to review.

A Brief History of GitHub Issues

GitHub Issues have long been the cornerstone of collaborative project management, enabling teams to track bugs, plan feature development, and prioritize workflows. Over time, GitHub has enriched this foundational system with tools like labels, milestones, and task lists. However, as projects increased in complexity, managing hierarchical tasks within issues became increasingly challenging.

The introduction of sub-issues represents a significant leap forward—empowering teams to manage nested relationships while retaining the simplicity and intuitive functionality that are core to GitHub’s user experience.

The Journey of Building Sub-Issues

Developing sub-issues was an ambitious effort that required careful design, technical innovation, and collaboration across teams. The goal was to create a feature deeply integrated into GitHub Issues that offered advanced functionality without adding unnecessary complexity.

Hierarchical Design

The GitHub team began by designing a new hierarchical structure for tasks rather than modifying existing task lists. This involved updates to data models and rendering logic to support nested relationships between parent issues and sub-issues.

Efficient Data Modeling

The sub-issues table in the database stores relationships between parent and child issues, ensuring that hierarchical links are maintained. Additionally, progress data is rolled up into a separate table for sub-issue completion, allowing for fast queries without traversing the entire sub-issue list.

GraphQL Integration

Sub-issues leverage GitHub’s GraphQL endpoints for efficient data fetching and flexibility. This approach allowed GitHub to implement optimized list-view components while reusing and enhancing existing components within the React ecosystem.

Accessibility and Ease of Use

Great care was taken to ensure sub-issues were intuitive and accessible. GitHub worked closely with its accessibility designers and shared components team to ensure users could create, edit, and manage sub-issues seamlessly without disrupting their workflows.

Using Sub-Issues in Practice

GitHub’s “dogfooding” approach—using its own feature during development—played a key role in refining sub-issues. Teams across the company used sub-issues to manage complex projects, track progress, and ensure dependencies were met.

Key Benefits Reported

• Improved visibility into large projects by breaking tasks into smaller items.
• Enhanced control over task prioritization and dependencies.
• Simplified workflows with hierarchical task structures.

The feedback collected during this internal usage helped GitHub identify areas for improvement, ensuring a polished and user-friendly feature before release.

Gathering Early Feedback and Continuous Improvement

Feedback from early beta testers was instrumental in shaping the final product. During testing, users highlighted the importance of metadata in sub-issue lists. Initially, only issue titles were displayed, but enhancements like issue numbers and repository names were added based on community suggestions.

Example Enhancements

• Filters like has:sub-issues-progress and has:parent-issue evolved from discussions around how to better manage task hierarchies.
• Improved filtering syntax ensured users could navigate and organize sub-issues effectively.

This iterative approach underscored GitHub’s commitment to building features that truly meet the needs of its community.

Sub-issues are now available and ready to help teams break down complex tasks into manageable pieces. Whether you’re organizing cross-repository projects, tracking dependencies, or simply seeking a more structured workflow, sub-issues offer powerful tools to enhance your project management experience.