Issue Type Relationships
How to connect issues through parent-child relationships within Zenhub's hierarchy
Understanding Parent-Child Relationships
Parent-child relationships connect issues within Zenhub's hierarchy, creating structure from high-level goals down to implementation tasks. An issue becomes a parent when other issues are linked beneath it as children (also called sub-issues). For example, an Epic (Level 3) might have multiple Task issues (Level 4) as children, while that Epic itself is a child of a Project (Level 2).
These relationships drive automatic behaviors including progress roll-up from children to parents, automatic issue type suggestions for new children, and visual hierarchy displays in Goals & Planning Panel. You can add, remove, or reassign parent-child connections at any time as your project evolves.
Understanding GitHub and Zenhub Issue Relationships
Parent-child relationships work differently for GitHub and Zenhub issues based on where they exist.
GitHub Issues live in GitHub repositories and integrate with pull requests and commits. They can have any issue as a parent, but their children must be GitHub Issues to maintain GitHub's native parent-child tracking.
Zenhub Issues exist only in Zenhub for planning and coordination work. They offer more flexibility - they can have both GitHub and Zenhub children, making them ideal for strategic levels in your hierarchy.
Why this matters for planning:
If you create a GitHub Issue as an Epic, all its children must also be GitHub Issues. If you create a Zenhub Issue as a Project, its children can be either GitHub or Zenhub Issues, giving you more flexibility.
Most teams use Zenhub Issues for strategic planning levels (Levels 1-3: Initiatives, Projects, Epics) and GitHub Issues for implementation work (Levels 4-5: Bugs, Tasks, Sub-tasks). This approach keeps strategic planning flexible while maintaining GitHub integration for development work.
NOTE: Some legacy GitHub issues may show Zenhub children from before this constraint existed. If you remove these legacy connections, you cannot re-add them.
Setting Parent Relationships
Zenhub provides multiple ways to establish parent-child connections depending on your workflow.
During or after issue creation: Use the "Parent Issue" field in the right sidebar to search for and select a parent. The Smart Parent Selector automatically shows the most relevant options - when setting a parent for a Level 4 issue (Task, Bug, Story), it defaults to showing Level 3 issues (Epics). Click "All Issues" to search across all levels when you need non-standard relationships.
From parent's sub-issues section: Open a parent issue, navigate to "Sub-issues," and click "+ Add Issue" to link existing issues or create new children directly beneath the parent. This works well when starting with the parent and breaking it down into children.
Bulk operations on Work Tracker: Select multiple issues using multi-select mode, then use "Set Parent" to assign them all to the same parent simultaneously. This is efficient during planning sessions when organizing many related issues.
From Goals & Planning Panel: Click the blue "+" icon next to any parent issue to create a new child pre-linked to that parent, with its issue type automatically set to the appropriate hierarchy level. This streamlined method works best for strategic work (Levels 1-3).
TIP: The Smart Parent Selector shows the "next level up" by default (Level 4 issues see Level 3 parents), matching natural hierarchy flow. Override this by clicking "All Issues" when you need to skip levels or establish cross-cutting relationships.
Where Relationships Appear
Parent-child relationships display differently across Zenhub views, optimized for different workflows:
View | What You See | Best For |
|---|---|---|
Goals & Planning Panel | Expandable tree with visual connections, progress indicators, drag-and-drop reorganization | Strategic planning, understanding complete hierarchy (Levels 1-3 by default) |
Work Tracker | Parent info on issue cards, filter by parent to see all children across pipelines | Sprint execution, focusing on specific Epic or Project work |
Timeline View | Parents as timeline bars with nested children | Release planning, chronological alignment of parent and child work |
Issue View | Parent in sidebar with click-through navigation, Sub-issues section with status and progress | Managing individual issue relationships, tracking completion |
Filter by parent in Work Tracker or Goals & Planning to focus on all children of a specific parent, regardless of sprint assignment or pipeline status.
Automatic Behaviors and Managing Relationships
Automatic sub-issue type assignment: When you create a child issue from a parent, Zenhub automatically assigns an appropriate issue type based on the parent's level. Creating a child under an Epic (Level 3) automatically assigns the default Level 4 issue type (typically "Task" or "Story"). Override these assignments by manually changing the child's issue type after creation.
Progress roll-up calculation: Parent issues automatically calculate completion percentages based on their children's status. Progress uses both issue counts and story point totals, rolling up through multiple hierarchy levels. Close a sub-task and watch it affect its parent task, which affects its parent epic, up through the hierarchy.
Changing parent assignments: Open any child issue and use the parent selector to assign a different parent. The issue immediately moves to its new hierarchy position, and progress indicators update on both old and new parents. Bulk operations let you reassign multiple children simultaneously when restructuring projects.
Removing parent connections: Click the "x" next to the parent name to remove the connection entirely. The issue remains in your workspace but no longer participates in hierarchy roll-ups or parent-focused filtering. Removing a parent doesn't delete the child issue or affect its other metadata like story points or assignments.
Common Workflow Patterns
Epic-driven development: Teams practicing Scrum structure work around Epics (Level 3) containing Stories and Tasks (Level 4) completed within sprints. Sub-tasks (Level 5) break Stories into small implementation steps.
Project-based organization: Product teams organize around Projects (Level 2) representing major releases, with multiple Epics (Level 3) grouped by feature area. This coordinates cross-team efforts and tracks progress toward major milestones.
Initiative planning: Organizations use Initiatives (Level 1) for quarterly or yearly goals, with Projects, Epics, and lower levels creating complete hierarchy from strategy to execution.
Mixed approaches: Many teams combine these patterns, using different hierarchy depths for different work types. Strategic projects might go five levels deep, while operational work stays at three levels. The flexible system accommodates varied needs within a single workspace.
FAQ
Q: Can I connect issues across different repositories?
A: Yes, parent-child relationships work across all repositories in your workspace. A parent issue in one repository can have children in different repositories, making it easy to coordinate multi-repo projects.
Q: What happens to child issues when I close a parent?
A: Closing a parent issue doesn't automatically close its children. Children remain open and retain their parent connection. You must explicitly close children or use bulk operations if you want to close the entire hierarchy.
Q: Can an issue have multiple parents?
A: No, each issue can have only one direct parent at any time. However, an issue can have grandparents and great-grandparents through the hierarchy chain, so it participates in multiple levels of roll-up calculations.
Q: Why can't I make a GitHub Issue the child of a Zenhub Issue?
A: This is actually supported! Zenhub Issues CAN be parents of GitHub Issues. The constraint only goes one direction: GitHub Issues cannot be parents of Zenhub Issues.
Q: How do parent-child relationships affect sprint planning?
A: Sprint planning should focus on Level 4 and 5 issues (Tasks, Bugs, Stories, Sub-tasks) that are children of Epics. While you can add higher-level issues (Initiatives, Projects, Epics) to sprints, these typically span longer than a sprint duration. Progress on Level 4 and 5 work rolls up to parent Epics, letting you track feature completion within sprints while maintaining the bigger picture in your hierarchy.
Q: Can I see all children of a parent across multiple sprints?
A: Yes, filter by parent issue in Work Tracker or Goals & Planning to see all children regardless of sprint assignment. This view helps track Epic progress over multiple sprint cycles.