Skip to main content

Creating Sub-Issues

Zenhub supports sub-issues, so you can break down your work in a multi-level issue hierarchy that fits your organizational needs. This guide will show how you can create sub-issue relationships, both for existing issues, and when creating new issues.

Note: GitHub issues can have parents that are either GitHub or Zenhub issues, while Zenhub issues can only have Zenhub issues as parents.

Example: adding existing issues as a sub-issue​

If you already have two issues and want to create a sub-issue relationship between them, you can use the addSubIssues mutation as follows:

mutation addSubIssues(
  $childIssueIds: [ID!]!
  $parentIssueId: ID!
) {
  addSubIssues(input: {
    childIssueIds: $childIssueIds,
    parentId: $parentIssueId
  }) {
    failedIssues {
      id
    }
    successCount
  }
}

You'll need the id of the parent Issue, as well as the ids of any issues you want to add as children (you can add multiple sub-issues in one operation). You can use this mutation to create subissues of Zenhub of GitHub issues.

Example: creating a sub-issue as a new issue​

To create a brand new sub-issue for an existing issue, use the createIssue mutation with:

  • parentIssueId - the id of the issue you want to create a sub-issue within

  • repositoryId - the id of the repository (GitHub or Zenhub) that the new issue should be created in

    • For GitHub issues, this will be the GraphQL ID of the GitHub repository
    • For Zenhub issues, this usually corresponds to the workspace you're in. Learn more

    For more on getting repository IDs, see Getting Entity IDs

The mutation to create a sub-issue in this way looks exactly like creating a normal issue, with the addition of parentIssueId:

mutation createNewSubissue($repositoryId: ID!, $title: String!, $body: String) {
  createIssue(input: {
    repositoryId: $repositoryId,
    title: $title,
    body: $body,
    parentIssueId: $parentIssueId
  }) {
    issue {
      id
      title
    }
  }
}

Remember that Zenhub issues can not be sub-issues of GitHub issues, since you can't view Zenhub issues on GitHub. So when creating a sub-issue as a Zenhub issue, parentIssueId must correspond to a Zenhub issue as well.