Working with Issues

This guide covers creating, reading, updating, and deleting issues in Zenhub, including how to work with issue types to create strategic work items like Epics, Projects, and Initiatives.

Understanding Issue Types

Issues in Zenhub can have different types that define their nature and hierarchy. There are two kinds of issue types:

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

Both types share the same core structure:

issueType {
  ... on ZenhubIssueType {
    id
    name
    disposition
    level
    color
    description
  }
  ... on GithubIssueType {
    id
    name
    disposition
    level
    color
    description
  }
}

Issue Type Properties

• level: Integer from 1-5 indicating hierarchy level (1 = highest level like Initiative, 5 = lowest like Task)
• disposition: Either BOARD (appears on board) or PLANNING_PANEL (appears in Goals & Planning panel)
• name: Display name for the issue type
• color: Hex color code for visual identification
• description: Optional description of the issue type

Creating Issues

Basic Issue Creation

Create a simple issue:

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

Variables:

{
  "CreateIssueInput": {
    "title": "My new issue",
    "body": "Issue description",
    "repositoryId": "REPOSITORY_ID"
  }
}

Creating Issues with Specific Issue Types

First, get available issue types for your repository:

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

Then create an issue with a specific issue type:

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

Variables:

{
  "CreateIssueInput": {
    "title": "My Epic",
    "body": "Epic description",
    "repositoryId": "REPOSITORY_ID",
    "issueTypeId": "ISSUE_TYPE_ID"
  }
}

Creating Issues with Labels and Assignees

For GitHub issues:

{
  "CreateIssueInput": {
    "title": "My GitHub issue",
    "body": "Issue description",
    "repositoryId": "GITHUB_REPOSITORY_ID",
    "labels": ["bug", "high-priority"],
    "assignees": ["username1", "username2"]
  }
}

For Zenhub issues (labels and assignees are handled separately):

{
  "CreateIssueInput": {
    "title": "My Zenhub issue",
    "body": "Issue description",
    "repositoryId": "ZENHUB_REPOSITORY_ID",
    "zenhubLabelInfos": [
      {"name": "bug", "color": "#d73a4a"},
      {"name": "high-priority", "color": "#b60205"}
    ],
    "zenhubAssigneeIds": ["ZENHUB_USER_ID_1", "ZENHUB_USER_ID_2"]
  }
}

Note: When creating Zenhub Issues, the createIssue mutation does not currently support the labels and assignees variables. To set labels and assignees for your Zenhub Issues, please call the addZenhubLabelsToIssues and addZenhubAssigneesToIssues mutations after creating your Zenhub Issue.

Reading Issues

Get Issues in a Workspace

Get all issues in a workspace with their issue types:

query workspaceIssues($workspaceId: ID!) {
  workspace(id: $workspaceId) {
    issues {
      nodes {
        id
        title
        number
        state
        type
        issueType {
          ... on ZenhubIssueType {
            id
            name
            disposition
            level
          }
          ... on GithubIssueType {
            id
            name
            disposition
            level
          }
        }
      }
    }
  }
}

Get Strategic Issues (Goals & Planning Panel)

Get issues that appear in the Goals & Planning panel:

query getStrategicIssues($workspaceId: ID!, $zorgId: ID!) {
  node(id: $zorgId) {
    ... on ZenhubOrganization {
      searchStrategicIssues(
        workspaceId: $workspaceId,
        order: { field: CREATED_AT, direction: DESC }
      ) {
        nodes {
          issue {
            id
            number
            title
            type
            state
            issueType {
              ... on ZenhubIssueType {
                id
                name
                level
                disposition
              }
              ... on GithubIssueType {
                id
                name
                level
                disposition
              }
            }
          }
        }
      }
    }
  }
}

Get a Single Issue

query getIssue($issueId: ID!) {
  node(id: $issueId) {
    ... on Issue {
      id
      title
      body
      number
      state
      type
      issueType {
        ... on ZenhubIssueType {
          id
          name
          level
          disposition
          color
        }
        ... on GithubIssueType {
          id
          name
          level
          disposition
          color
        }
      }
      repository {
        id
        name
      }
    }
  }
}

Updating Issues

Update Issue Details

Here's a simple example of a mutation that modifies an issue's title and body fields:

mutation updateIssue($issueId: ID!, $title: String, $body: String) {
  updateIssue(input: {
    issueId: $issueId,
    title: $title,
    body: $body
  }) {
    issue {
      id
      title
      body
    }
  }
}

Change Issue Types

Change the issue type of one or more existing issues:

mutation changeIssueType($input: ChangeIssueTypeOfIssuesInput!) {
  changeIssueTypeOfIssues(input: $input) {
    successCount
    failedIssues {
      id
      title
    }
    githubErrors
  }
}

To add or change the issue type for one or more issues, your $input variable for the above mutation should like like this:

{
  "input": {
    "issueIds": ["ISSUE_ID_1", "ISSUE_ID_2"],
    "issueTypeId": "NEW_ISSUE_TYPE_ID"
  }
}

If you want to remove an issue type from one or more issues, use the same changeIssueTypeOfIssues mutation but pass "removeIssueType": true instead of the issueTypeId field:

{
  "input": {
    "issueIds": ["ISSUE_ID_1", "ISSUE_ID_2"],
    "removeIssueType": true
  }
}

Close an Issue

mutation closeIssue($issueId: ID!) {
  updateIssue(input: {
    issueId: $issueId,
    state: "CLOSED"
  }) {
    issue {
      id
      state
    }
  }
}

Related Guides

• Sub-Issues - Learn how to create hierarchical relationships between issues
• Issue Types - Learn how to create and manage issue types themselves
• Getting Entity IDs - How to find workspace, repository, and organization IDs

Best Practices

1. Use Meaningful Titles: Make issue titles clear and actionable
2. Choose Appropriate Issue Types: Use higher-level types (1-3) for strategic work, lower levels (4-5) for implementation tasks
3. Consistent Repository Usage: Use Zenhub repositories for internal planning, GitHub repositories for development work
4. Label Organization: Use consistent labeling strategies across your team