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 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.
Level | Default name | Description | Typical timeframe | Default view |
|---|---|---|---|---|
1 | Initiative | Big picture goals aligned with long-term strategy | Quarters to years | Goals & Planning Panel, Timeline |
2 | Project | Cohesive efforts with defined objectives and deliverables | Several months | Goals & Planning Panel, Timeline |
3 | Epic | Themes of work grouping related issues around specific features | Weeks to months | Goals & Planning Panel, 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 |
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:
https://github.com/organizations/YOUR_GITHUB_ORGANIZATION_NAME/settings/issue-types
Add at least the 4 core types: Initiative, Project, Epic, and Sub-task. These names can be customized to match your organization's terminology. Zenhub will integrate any additional types you add automatically.
NOTE: A 404 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 the hierarchy in Zenhub
Your Zenhub organization admin establishes the hierarchy that maps GitHub issue types to Zenhub's 5-level structure. Navigate to:
https://app.zenhub.com/settings/o/YOUR_ZENHUB_ORGANIZATION_NAME/issue-types
Or access through Account Management → Organization Settings → Issue Types.
Assigning types to hierarchy levels
Click the three-dot menu next to an issue type, select Edit, choose the hierarchy level, and save.
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, select Edit, and toggle the switch to mark it as default. This default type is automatically suggested when creating sub-issues.
Creating custom issue types
Create up to 25 custom issue types in the configuration page using the Add Issue Type button. 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 synchronization
Issue types synchronize bidirectionally with GitHub's native issue type system when you have GitHub organization owner permissions. Once connected, types created in Zenhub appear in GitHub automatically, and vice versa.
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 prompts synchronization to GitHub even without owner permissions, and types will sync retroactively when owner permissions are eventually granted.
Troubleshooting
Synchronization not working
Verify you have GitHub organization owner permissions and that the GitHub organization is properly connected to your Zenhub organization in 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.
Next steps
Share the hierarchy structure with your team so everyone understands the levels
Document any custom types you've created and their intended use cases
Review Using Issue Types for daily workflow guidance
Train team members on when to use each hierarchy level
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.
Q: What happens to existing issues when I change issue type configuration?
A: Existing issues retain their assigned types. Relationships and categorizations don't change retroactively unless you manually update individual issues.
Q: What GitHub permissions do I need?
A: You need GitHub organization admin permissions to add issue types in GitHub, and Zenhub organization admin permissions to configure the hierarchy in Zenhub. Automatic synchronization between GitHub and Zenhub requires GitHub organization owner permissions.
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. 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.