Using Issue Types
Set and change issue types to organize work within your team's hierarchy
This article is for team members who want to assign issue types to their work. Use this guide when you're creating an issue and need to assign it a type (Initiative, Project, Epic, Task, etc.), changing an existing issue's type, or organizing your work within the hierarchy.
Understanding Your Organization's Hierarchy
Your organization's admins have configured a five-level hierarchy that categorizes all work. Understanding these levels helps you create and organize issues appropriately.
Quick reference:
Level 1 (Initiative/Objective): Big picture goals spanning quarters or years
Level 2 (Project): Major efforts taking several months
Level 3 (Epic): Feature themes spanning weeks to months
Level 4 (Bug/Task/Enhancement/Story): Day-to-day work completed in days to weeks
Level 5 (Sub-task): Granular tasks measured in hours to days
All work in Zenhub starts as an issue - the type you assign determines which hierarchy level that issue represents. Creating an Epic means creating an issue and setting its type to "Epic."
NOTE: Issue type names may differ in your organization if admins customized the default terminology. Check your organization's configuration if the types you see don't match these examples.
Setting and Changing Issue Types
Set an issue's type during creation or change it anytime afterward using the same process.
To set or change an issue type:
Open the issue (or during creation, look at the right sidebar)
Click the "Issue type" dropdown in the right sidebar
Select the desired type from the list organized by hierarchy level
The change saves automatically
To remove an issue type: Click the "Issue type" dropdown and deselect the currently selected type. Only one type can be selected at a time, so deselecting removes the type assignment.
The issue type dropdown shows descriptions for each type (like "Level 1: for big picture goals" and "Level 3: for larger bodies of work") to help you choose the appropriate level for your work.
TIP: The hierarchy system is flexible - promote or demote issues between levels as your understanding of the work evolves. Just change the issue type to reflect the actual scope.
Where Issue Types Appear
Different hierarchy levels appear in different Zenhub views by default, keeping strategic planning separate from daily execution.
Issue Type Level | Default Views | Purpose |
|---|---|---|
Levels 1, 2, 3 | Goals & Planning Panel, Timeline | Strategic planning and roadmap visualization |
Levels 4, 5 | Work Tracker, Reports | Daily execution and sprint work |
Viewing strategic levels on Work Tracker: Use the Issue Type filter on your Work Tracker to display Level 1/2/3 issue types when you need to see how strategic work breaks down into execution tasks.
Viewing execution levels in Goals & Planning: Level 4 issues can be added to the Goals & Planning Panel through the panel's settings if your organization needs additional hierarchy visibility. Your admin controls this setting.
How Automatic Behaviors Work
Zenhub automates several hierarchy-related workflows to reduce manual work and maintain consistent structure.
Smart parent suggestions: When setting a parent for an issue, Zenhub automatically suggests issues from the appropriate hierarchy level. Assigning a parent to a Level 4 Task defaults to showing Level 3 Epics as available parents. You can override these suggestions by searching for issues at any level if needed.
Automated sub-issue type assignment: When creating sub-issues under a parent, Zenhub automatically assigns the default issue type for the next level down. Creating a sub-issue under an Epic (Level 3) automatically assigns it the default Level 4 type (typically "Task"), streamlining issue creation without manual type selection.
Common Workflows and Patterns
Creating any issue using the green Create button
Click the green "+ Create" button (works for any hierarchy level)
Select GitHub Issue or Zenhub Issue
Set the issue type dropdown to your desired level
The issue appears in the appropriate default view based on type
Creating strategic work (Initiatives, Projects, Epics) in Goals & Planning Panel
Open Goals & Planning Panel (available in Work Tracker or Timeline)
Click the blue "+" icon
Click the GitHub issue icon (green circle with dot) to switch to Zenhub Issue if desired
Select the issue type from the list
The issue is created with the type pre-populated
This Goals & Planning method works the same as the green Create button but pre-selects the strategic issue type, streamlining Level 1/2/3 creation.
Breaking down strategic work into tasks
Open a strategic issue (Epic, Project, or Initiative)
Create sub-issues using the "+ Add Issue" button
Zenhub automatically assigns the appropriate type for the next level down
Sub-issues appear on Work Tracker while parent remains in Goals & Planning
Reclassifying work as scope changes
Open the issue that needs reclassification
Change its issue type to reflect the new scope
The issue automatically moves to the appropriate default view
Parent-child relationships remain intact
Troubleshooting Issue Type Problems
Types not appearing in dropdown: Ensure your organization's admins have configured issue types. See Establishing Issue Types for setup guidance, or contact your Zenhub organization admin if you don't see expected types available.
Can't change issue type: Verify you have write permissions for the repository. Read-only access allows viewing issues but prevents modifications.
Parent suggestions showing wrong level: This is expected behavior - Zenhub suggests parents from one level up in the hierarchy. Use the search function to override suggestions if you need to assign a parent from a different level.
Issue disappeared after changing type: The issue moved to a different default view. Strategic types (Levels 1-3) appear in Goals & Planning Panel, while execution types (Levels 4-5) appear on Work Tracker. Use filters or switch views to locate the issue.
Advanced Usage Scenarios
Cross-level parent assignments: While Zenhub defaults to suggesting parents from one level up, you can assign parents from any level by using the search function in the parent selector. This flexibility supports complex organizational structures but should be used sparingly to maintain clear hierarchy.
Mixing strategic and execution work: Some teams prefer seeing all work types together on the Work Tracker. Use the Issue Type filter to display Level 1/2/3 types alongside execution work, but be aware this may impact board performance with large issue counts.
Custom type workflows: If your organization created custom issue types beyond the defaults, ask your admin about their intended use cases and when to apply each type. Custom types often represent specialized workflows unique to your organization.
FAQ
Q: How do Issue Types differ from Labels?
A: Issue Types define hierarchical work structure and parent-child relationships, while Labels provide flexible categorization across any dimension (priority, component, status). Use Issue Types for structural organization and Labels for cross-cutting concerns.
Q: Can I have multiple issue types on one issue?
A: No, each issue can only have one issue type assigned at a time. This ensures clear hierarchy and prevents confusion about which level the issue represents.
Q: What happens when I change an issue's type?
A: The issue automatically moves to the default view for that type level. Strategic types (1-3) move to Goals & Planning Panel, execution types (4-5) move to Work Tracker. Parent-child relationships and other metadata remain unchanged.
Q: Do I need special permissions to change issue types?
A: You need write permissions for the repository containing the issue. The same permissions that allow you to edit issue descriptions also allow you to change issue types.
Q: How do I know which issue type to use?
A: Consider the scope and timeframe: work spanning months = Epic or Project, work completed in days = Task or Bug, work measured in hours = Sub-task. The dropdown descriptions provide guidance for each level.
Q: Can I see all issue types across all views?
A: Yes, use filters on each view to display issue types that don't appear by default. The Issue Type filter on Work Tracker shows strategic levels, and Goals & Planning settings can show execution levels (though this may impact performance).
Q: How do I create an Epic or Project?
A: Creating an epic or project means creating a new issue and assigning it the Epic or Project issue type. See Creating Issues for the full workflow. You can set the issue type during creation or change it afterward using the issue type dropdown.
Q: How do I create a new custom issue type like "Feature" or "Technical Debt"?
A: You can't create custom types from the issue level - they must be configured by your organization admin. See Establishing Issue Types for admin configuration, or ask your Zenhub organization admin to add the custom type you need.