Skip to main content

Working with Issues and Issue Types

Focused Guides Available

This overview has been split into focused guides for better usability:

For specific tasks, use the focused guides above.

Zenhub uses a hierarchical issue system where issues can have different types (such as Epic, Project, or Initiative) and can be organized into parent-child relationships through sub-issues. This overview explains the concepts and directs you to the appropriate detailed guides.

Core Concepts​

Issue Types​

Issue types define the nature and hierarchy of your work items:

  • Levels 1-2: Strategic items (Initiatives, Epics) - typically in Planning Panel
  • Levels 3-5: Execution items (Stories, Tasks, Sub-tasks) - typically on Boards
  • Two variants: ZenhubIssueType (Zenhub-only) and GithubIssueType (synced with GitHub)

➜ Learn more about Issue Types

Issues​

Standard work items that can be assigned types and organized hierarchically:

  • Basic CRUD operations (Create, Read, Update, Delete)
  • Type assignment and updates
  • State management and lifecycle

➜ Learn more about Working with Issues

Sub-Issues​

Parent-child relationships between issues for hierarchical organization:

  • Break down large work into smaller pieces
  • Multi-level hierarchies (Initiative → Epic → Story → Task)
  • Progress tracking across levels

➜ Learn more about Sub-Issues

Quick Examples​

Creating a Strategic Issue​

mutation createIssue($CreateIssueInput: CreateIssueInput!) {
  createIssue(input: $CreateIssueInput) {
    issue {
      id
      title
      issueType {
        ... on ZenhubIssueType {
          name
          level
        }
      }
    }
  }
}

Variables:

{
  "CreateIssueInput": {
    "title": "User Authentication Epic",
    "body": "Improve user authentication system",
    "repositoryId": "ZENHUB_REPOSITORY_ID",
    "issueTypeId": "EPIC_ISSUE_TYPE_ID"
  }
}

Creating a Sub-Issue​

mutation createSubIssue($CreateIssueInput: CreateIssueInput!) {
  createIssue(input: $CreateIssueInput) {
    issue {
      id
      title
      parentIssue {
        id
        title
      }
    }
  }
}

Variables:

{
  "CreateIssueInput": {
    "title": "Implement 2FA",
    "body": "Add two-factor authentication",
    "repositoryId": "GITHUB_REPOSITORY_ID", 
    "parentIssueId": "EPIC_ID",
    "issueTypeId": "STORY_ISSUE_TYPE_ID"
  }
}

Creating an Issue Type​

mutation createIssueType($input: CreateInput!) {
  createIssueTypeOption(input: $input) {
    issueTypeOption {
      id
      name
      level
      disposition
    }
  }
}

Variables:

{
  "input": {
    "name": "Epic",
    "level": 2,
    "disposition": "PLANNING_PANEL",
    "color": "#6366f1",
    "zenhubOrganizationId": "ZORG_ID",
    "isEnabled": true
  }
}

Common Workflow Patterns​

Strategic Planning Flow​

  1. Create Initiative (Level 1) for quarterly goals
  2. Break into Epics (Level 2) for major features
  3. Define Stories (Level 3) for user requirements
  4. Create Tasks (Level 4) for implementation work

Implementation Workflow​

  1. Plan work with strategic items in Goals & Planning panel
  2. Create implementation issues on workspace boards
  3. Link implementation work to strategic items via sub-issues
  4. Track progress through the hierarchy

Migration from Legacy Systems​

If you're migrating from legacy Epics or Projects:

  1. Audit existing items: Review your current epic/project structure
  2. Design issue type hierarchy: Plan your level 1-5 structure
  3. Create issue types: Set up the types you need
  4. Convert existing items: Use issue type change mutations
  5. Establish new workflows: Train your team on the new structure

The new issue type system provides more flexibility while maintaining organizational benefits.