Skip to main content

Creating Sub-Issues

Updated Documentation

This guide provides concrete examples for sub-issue creation. For more comprehensive coverage, see our focused guides:

For new implementations, we recommend using the focused guides above.

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 or 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($CreateIssueInput: CreateIssueInput!) {
  createIssue(input: $CreateIssueInput) {
    issue {
      id
      title
      parentIssue {
        id
        title
      }
    }
  }
}

Variables:

{
  "CreateIssueInput": {
    "repositoryId": "REPOSITORY_ID",
    "title": "Sub-task title",
    "body": "Sub-task description",
    "parentIssueId": "PARENT_ISSUE_ID"
  }
}

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.

Working with Issue Types and Sub-Issues​

You can also create sub-issues with specific issue types to maintain a clear hierarchy:

{
  "CreateIssueInput": {
    "repositoryId": "REPOSITORY_ID",
    "title": "User Story",
    "body": "As a user, I want to...",
    "parentIssueId": "EPIC_ISSUE_ID",
    "issueTypeId": "STORY_ISSUE_TYPE_ID"
  }
}

This allows you to create structured hierarchies like:

  • Initiative (Level 1) → Epic (Level 2) → Story (Level 3) → Task (Level 4)

For more advanced patterns and comprehensive sub-issue management, see the Sub-Issues guide.