Skip to main content

Issue Types

Issue types define the nature and hierarchy of your work items in Zenhub. This guide covers how to create, read, update, and delete issue types to organize your work effectively.

Understanding Issue Types​

Issue types help categorize and organize work items with different levels of hierarchy and purposes. They determine where issues appear in your workspace and how they relate to each other.

Types of Issue Types​

  • ZenhubIssueType: Issue types that only exist within Zenhub
  • GithubIssueType: Issue types that are synced with GitHub repositories

Key Properties​

  • level: Integer from 1-5 indicating hierarchy (1 = highest level like Initiative, 5 = lowest like Sub-task)
  • disposition: Where the issue type appears:
    • PLANNING_PANEL: Shows in Goals & Planning panel for strategic work
    • BOARD: Shows on workspace boards for day-to-day work
  • name: Display name for the issue type
  • color: Hex color code for visual identification
  • description: Optional description explaining the issue type's purpose
  • isDefault: Whether this is the default issue type for the organization
  • isDefaultForLevel: Whether this is the default issue type for its level
  • isEnabled: Whether the issue type is currently active

Creating Issue Types​

Create a Zenhub Issue Type​

mutation createIssueType($input: CreateInput!) {
  createIssueTypeOption(input: $input) {
    issueTypeOption {
      id
      name
      level
      disposition
      color
      description
      isEnabled
      isDefault
      isDefaultForLevel
    }
  }
}

Variables:

{
  "input": {
    "name": "Epic",
    "level": 2,
    "disposition": "PLANNING_PANEL",
    "color": "#6366f1",
    "description": "Large features or initiatives that span multiple sprints",
    "zenhubOrganizationId": "ZENHUB_ORGANIZATION_ID",
    "isEnabled": true,
    "isDefault": false,
    "isDefaultForLevel": true
  }
}

Common Issue Type Examples​

Initiative (Level 1)​

{
  "input": {
    "name": "Initiative",
    "level": 1,
    "disposition": "PLANNING_PANEL",
    "color": "#7c3aed",
    "description": "High-level strategic goals for the quarter or year",
    "zenhubOrganizationId": "ZENHUB_ORGANIZATION_ID",
    "isEnabled": true
  }
}

Epic (Level 2)​

{
  "input": {
    "name": "Epic",
    "level": 2,
    "disposition": "PLANNING_PANEL",
    "color": "#6366f1",
    "description": "Large features or capabilities",
    "zenhubOrganizationId": "ZENHUB_ORGANIZATION_ID",
    "isEnabled": true
  }
}

Story (Level 3)​

{
  "input": {
    "name": "Story",
    "level": 3,
    "disposition": "BOARD",
    "color": "#10b981",
    "description": "User-facing features or requirements",
    "zenhubOrganizationId": "ZENHUB_ORGANIZATION_ID",
    "isEnabled": true
  }
}

Task (Level 4)​

{
  "input": {
    "name": "Task",
    "level": 4,
    "disposition": "BOARD",
    "color": "#f59e0b",
    "description": "Implementation work or technical tasks",
    "zenhubOrganizationId": "ZENHUB_ORGANIZATION_ID",
    "isEnabled": true
  }
}

Sub-task (Level 5)​

{
  "input": {
    "name": "Sub-task",
    "level": 5,
    "disposition": "BOARD",
    "color": "#8b5cf6",
    "description": "Small pieces of work within a larger task",
    "zenhubOrganizationId": "ZENHUB_ORGANIZATION_ID",
    "isEnabled": true
  }
}

Reading Issue Types​

Get All Issue Types for an Organization​

query getIssueTypes($zenhubOrganizationId: ID!) {
  node(id: $zenhubOrganizationId) {
    ... on ZenhubOrganization {
      id
      issueTypeOptions {
        nodes {
          id
          name
          level
          disposition
          color
          description
          isEnabled
          isDefault
          isDefaultForLevel
          zenhubIssueType {
            issuesCount
          }
          hasRelatedGithubIssueTypes
          relatedGithubIssueTypes {
            id
            name
            issuesCount
            owner {
              id
              login
            }
          }
        }
        totalCount
      }
    }
  }
}

Get Available Issue Types for a Repository​

query getAssignableIssueTypes($repositoryId: ID!, $workspaceId: ID!) {
  node(id: $repositoryId) {
    ... on Repository {
      assignableIssueTypes(workspaceId: $workspaceId) {
        nodes {
          ... on GithubIssueType {
            id
            name
            level
            disposition
            color
            description
            isEnabled
          }
          ... on ZenhubIssueType {
            id
            name
            level
            disposition
            color
            description
            isEnabled
          }
        }
      }
    }
  }
}

Get a Specific Issue Type​

query getIssueType($issueTypeId: ID!) {
  node(id: $issueTypeId) {
    ... on IssueTypeOption {
      id
      name
      level
      disposition
      color
      description
      isEnabled
      isDefault
      isDefaultForLevel
      zenhubIssueType {
        issuesCount
        zenhubOrganization {
          id
          name
        }
      }
    }
  }
}

Updating Issue Types​

Update an Existing Issue Type​

mutation updateIssueType($input: UpdateInput!) {
  updateIssueTypeOption(input: $input) {
    issueTypeOption {
      id
      name
      level
      disposition
      color
      description
      isEnabled
      isDefault
      isDefaultForLevel
    }
  }
}

Variables:

{
  "input": {
    "issueTypeOptionId": "ISSUE_TYPE_OPTION_ID",
    "name": "Updated Epic",
    "level": 2,
    "disposition": "PLANNING_PANEL",
    "color": "#3b82f6",
    "description": "Updated description for epics",
    "isEnabled": true,
    "isDefault": false,
    "isDefaultForLevel": true
  }
}

Enable/Disable an Issue Type​

{
  "input": {
    "issueTypeOptionId": "ISSUE_TYPE_OPTION_ID",
    "isEnabled": false
  }
}

Change Issue Type Color​

{
  "input": {
    "issueTypeOptionId": "ISSUE_TYPE_OPTION_ID",
    "color": "#ef4444"
  }
}

Deleting Issue Types​

Delete an Issue Type​

mutation deleteIssueType($input: DeleteInput!) {
  deleteIssueTypeOption(input: $input) {
    issueTypeOption {
      id
    }
  }
}

Variables:

{
  "input": {
    "issueTypeOptionId": "ISSUE_TYPE_OPTION_ID"
  }
}
warning

Deleting an issue type will affect all issues currently using that type. Make sure to update or migrate issues to different types before deletion.

Issue Type Management Patterns​

Setting Up a Standard Hierarchy​

  1. Create Level 1 (Strategic):

    • Initiative
    • Theme
    • Objective

  2. Create Level 2 (Planning):

    • Epic
    • Feature
    • Project

  3. Create Level 3 (Implementation):

    • Story
    • Requirement
    • Bug

  4. Create Level 4 (Execution):

    • Task
    • Spike
    • Chore

  5. Create Level 5 (Granular):

    • Sub-task
    • Research Item

Disposition Strategy​

PLANNING_PANEL (Strategic Focus):

  • Levels 1-2: Initiatives, Epics
  • Long-term planning items
  • Cross-team coordination

BOARD (Execution Focus):

  • Levels 3-5: Stories, Tasks, Sub-tasks
  • Sprint planning items
  • Day-to-day work

Color Coding Strategy​

Consider using consistent color patterns:

{
  "level1": "#7c3aed",  // Purple - Strategic
  "level2": "#6366f1",  // Indigo - Planning
  "level3": "#10b981",  // Green - Features
  "level4": "#f59e0b",  // Amber - Tasks
  "level5": "#8b5cf6"   // Violet - Sub-tasks
}

Migrating from Legacy Epics/Projects​

If you're coming from legacy Epics or Projects, you can:

  1. Audit existing items: Query your current epics/projects
  2. Create appropriate issue types: Set up the hierarchy you need
  3. Convert existing items: Change their issue types using the mutation in Working with Issues
  4. Establish new workflows: Train your team on the new structure

Best Practices​

  1. Consistent Levels: Establish clear definitions for each level across your organization
  2. Meaningful Names: Use names that make sense to your team and stakeholders
  3. Color Strategy: Use consistent colors to help users quickly identify issue types
  4. Disposition Alignment: Put strategic items in Planning Panel, execution items on Boards
  5. Default Management: Set appropriate defaults to streamline issue creation
  6. Regular Review: Periodically review and adjust issue types based on team usage
  7. Documentation: Document your issue type definitions for team reference