Establishing Issue Types
Configure your organizational issue hierarchy to structure work from strategic goals down to individual tasks
This article is for organization admins who want to configure new custom issue types that become available organization-wide.
Use this guide when you need to add new type options like "Feature," "Technical Debt," or "Spike" that your entire team can then assign to issues.
Understanding the Issue Type Hierarchy
Issue Types provide a five-level hierarchy that organizes work from strategic initiatives down to granular tasks. This structure creates clear relationships between high-level goals and day-to-day development work.
Level | Default Name | Description | Typical Timeframe | Default View |
|---|---|---|---|---|
1 | Initiative | Big picture goals aligned with long-term strategy | Quarters to years | Goals & Planning, Timeline |
2 | Project | Cohesive efforts with defined objectives and deliverables | Several months | Goals & Planning, Timeline |
3 | Epic | Themes of work grouping related issues around specific features | Weeks to months | Goals & Planning, Timeline |
4 | Bug/Task/Enhancement/Story | Day-to-day development work | Days to weeks | Work Tracker, Reports |
5 | Sub-task | Granular tasks within larger issues | Hours to days | Work Tracker, Reports |
This hierarchical organization appears throughout Zenhub in the Goals & Planning Panel, Timeline view, and issue relationships, providing consistent structure for planning and tracking work at every scale.
How it works in practice: All work in Zenhub starts as an issue. Issue Types determine whether that issue represents an Initiative, Project, Epic, Task, or Sub-task. Creating an Epic means creating an issue and setting its type to "Epic."
Setting Up Issue Types in GitHub
Your GitHub Organization Admin must first configure Issue Types in GitHub before they can be used in Zenhub.
Navigate to GitHub Issue Types settings: Visit this URL, replacing YOUR_GITHUB_ORGANIZATION_NAME with your actual organization name:
https://github.com/organizations/YOUR_GITHUB_ORGANIZATION_NAME/settings/issue-types
Add the four core types for Zenhub:
Initiative
Project
Epic
Sub-task
These names can be customized to match your organization's terminology. Ensure you add at least three issue types above day-to-day issues (Levels 1-3) and one below (Level 5). Additional issue types can be added, and Zenhub will integrate them automatically.
NOTE: A "404 not found" error from GitHub typically means you don't have GitHub Organization Admin permissions. Contact your GitHub organization owner to either grant you admin access or complete this setup step.
Setting Up Your Issue Type Hierarchy in Zenhub
Your Zenhub Organization Admin establishes the hierarchy that maps GitHub issue types to Zenhub's five-level structure.
Navigate to Zenhub Issue Types settings: Visit this URL, replacing YOUR_ZENHUB_ORGANIZATION_NAME with your organization name:
https://app.zenhub.com/settings/o/YOUR_ZENHUB_ORGANIZATION_NAME/issue-types
Alternatively, access through Account Management (click your username at bottom left) → Organization Settings → Issue Types.
Assigning types to hierarchy levels: The configuration page displays five levels where you assign your GitHub issue types. To assign an issue type to a different level, click the three-dot menu next to the issue type in the configuration page, select "Edit," choose the hierarchy level, and save your changes.
Setting default types per level: For levels with multiple issue types (like Level 4 with Bug, Task, Enhancement), designate one as the default. Click the three-dot menu next to an issue type, select Edit, and toggle the switch to mark it as default. This default type will be automatically suggested when creating sub-issues.
Creating custom issue types: Beyond the GitHub types, create up to 25 custom issue types in the configuration page. Look for an "Add Issue Type" or "+" button, then specify the name, description, hierarchy level, color, and icon. Custom types help distinguish different work types at the same level, such as separating "Feature" from "Technical Debt" at Level 4.
GitHub Integration and Synchronization
Issue Types synchronize bidirectionally with GitHub's native issue type system when you have GitHub organization owner permissions configured.
Automatic synchronization: Once connected, issue types created in Zenhub automatically appear in GitHub, and types created in GitHub appear in Zenhub. This synchronization ensures consistent categorization whether team members work in Zenhub or GitHub directly.
Permission requirements: GitHub organization owner access is required for automatic synchronization. Without owner permissions, you can still configure Issue Types in Zenhub and assign them to GitHub issues, but the initial sync to GitHub won't occur automatically.
Manual Synchronization Without Owner Permissions
If you set up Issue Types before having owner permissions, you can trigger synchronization later by assigning issue types to actual GitHub issues in Zenhub. This action prompts the synchronization to GitHub even without owner permissions.
This workaround is useful when waiting for permission escalation or working in organizations with strict permission policies. Once types are assigned to issues in Zenhub, they'll sync to GitHub retroactively when owner permissions are eventually granted.
Troubleshooting Configuration Issues
Synchronization not working: Verify you have GitHub organization owner permissions. Check that the GitHub organization is properly connected to your Zenhub organization in the Integrations settings.
Types not appearing in configuration page: Ensure you've added issue types in GitHub first. Zenhub cannot create types directly - they must originate from GitHub's issue type system.
404 errors accessing settings: Confirm you have the correct permissions (GitHub Organization Admin for GitHub settings, Zenhub Organization Admin for Zenhub settings). Verify the organization name in your URL is correct.
Advanced Configuration Scenarios
Custom types exceeding limit: Zenhub allows up to 25 custom issue types total across all levels. If you've reached this limit, consider consolidating similar types or using labels for further categorization rather than additional issue types.
Type changes not syncing to GitHub: If you modify issue types in Zenhub but don't see changes reflected in GitHub, verify that bidirectional sync is enabled and you have the required owner permissions. Try reassigning the type to an issue to trigger a sync refresh.
Multiple organizations: Enterprise plans support up to 10 GitHub organizations. Configure issue types separately in each GitHub organization, then map them to Zenhub hierarchy levels independently.
Next Steps
Once your issue type hierarchy is configured:
Share the structure with your team so everyone understands the hierarchy levels
Document any custom types you've created and their intended use cases
Review the Using Issue Types article for daily workflow guidance
Train team members on when to use each hierarchy level
Set up workspace-specific views to optimize visibility for different teams
FAQ
Q: Can I have different issue type hierarchies for different workspaces?
A: No, Issue Types are configured at the organization level and apply to all workspaces. This ensures consistent work categorization across your entire organization, though individual workspaces can choose which types they actively use.
Q: What happens to existing issues when I change issue type configuration?
A: Existing issues retain their assigned types even if you rename or reconfigure those types. The relationships and categorizations don't change retroactively unless you manually update individual issues.
Q: What GitHub permissions do I need to configure Issue Types?
A: You need GitHub Organization Admin permissions to add issue types in GitHub's settings, and Zenhub Organization Admin permissions to configure the hierarchy in Zenhub. Automatic synchronization between GitHub and Zenhub requires GitHub organization owner permissions, though you can still configure and use types without it.
Q: How many custom issue types can I create?
A: Zenhub allows up to 25 custom issue types total across all hierarchy levels. If you need more categorization, use labels alongside issue types for additional flexibility.
Q: Can I rename issue types after creation?
A: Yes, you can rename issue types at any time. Changes apply to future issue creation but don't modify the names of existing issues. The type assignment remains unchanged - only the display name updates.