Sub-issues Public Preview

[github-staff]

Feedback wanted

Thank you for participating in the sub-issues public preview. Please leave your feedback below on what is working well, any bugs you encounter, and what else you’d like to see!

To provide your feedback on other experiences released at the same time, please visit:

• Issue Types Public Preview #139933
• Advanced Search for Issues Public Preview #139934
• Issues: Index, Create and Show Page Updates Public Preview #139935
• Increased Project Item Limits Public Preview #139936

Sub-issues

Sub-issues are designed to help you group and manage your issues with a parent/child relationship into a hierarchy.

Adding sub-issues

Any existing issue, where you have write access or above, will now have a 'create sub-issue' option, you can also use the drop down to opt to create an existing issue instead:

Alternatively, you will notice a new relationship section on the sidebar, allowing you to add from a child to a parent.

Viewing sub-issues

As you create sub-issues, you will start building a nested hierarchy of issues under your opening comment.

Clicking one of these issues now allows you to explore them directly from the main issue page via a slide out panel, making it easy to add a comment or update meta-data without losing context.

Working with sub-issues in projects

We have a couple of new fields in projects, sub-issue progress - which gives you a customisable (check out the settings page) progress pill or bar to see how your issues are progressing:

And parent issue - helping you see what the parent item of each issue is. Which works especially well in a group by or slice by format:

We will also shortly release a new workflow to keep a all child issues synced with a project which the parent already belongs to.

Webhooks

Sub-issue webhooks can be enabled at the repository or organization level and can be enabled/disabled separately from issue events.

Webhook events are now fired for the following actions:

• Sub-issue added
• Sub-issue removed
• Parent issue added
• Parent issue removed

GraphQL API

Sub-issues can also be managed via the GraphQL API. Note that these requests will need to include the GraphQL-Features header with a value of sub_issues.

Click to view Fields and Mutations

Fields

subIssuesSummary

Summary of the state of an issue's sub-issues

query summary {
  node(id: "I_123") {
    ... on Issue {
      subIssuesSummary {
        total
        completed
        percentCompleted
      }
    }
  }
}

parent

The parent entity of the issue.

query parent {
  node(id: "I_456") {
    ... on Issue {
      parent {
        title
      }
    }
  }
}

subIssues

A list of sub-issues associated with the Issue.

query subIssues {
  node(id: "I_123") {
    ... on Issue {
      subIssues(first: 10) {
        nodes {
          title
        }
      }
    }
  }
}

Mutations

addSubIssue

Adds a sub-issue to a given issue

If you'd like to replace the exist parent of a sub-issue, provide replaceParent: true

mutation addSubIssue {
  addSubIssue(input: { issueId: "I_123", subIssueId: "I_456" }) {
    issue {
      title
    }
    subIssue {
      title
    }
  }
}

removeSubIssue

Removes a sub-issue from a given issue

mutation removeSubIssue {
  removeSubIssue(input: { issueId: "I_123", subIssueId: "I_456" }) {
    issue {
      title
    }
    subIssue {
      title
    }
  }
}

reprioritizeSubIssue

Reprioritizes a sub-issue to a different position in the parent list.

mutation reprioritizeSubIssue {
  reprioritizeSubIssue(
    input: { issueId: "I_123", subIssueId: "I_456", afterId: "I_789" }
  ) {
    issue {
      title
    }
  }
}

Sub-issue limits

A couple of limits we have implemented that we would love feedback on:

• Sub-issue depth limit: 8
• Max sub-issues per level: 50
• Parents are unique ( an issue can only have one parent)

Next Steps

We would love your feedback on sub-issues and the new issues experience in general as your try it out! Please let us know what you think! 🎉

[probitcarwyn]

Can sub-issues reference issues in other repos, or is it like sub-tasks (tracked issues feature) limited to issues in the same repo? Are sub-issues replacing tasks-lists?

Update: We now have the beta enabled and I can confirm that sub-issues can be cross-repo.

Actually, clarifying how sub-issues relate (or not) to task-lists would be useful. We have the beta enabled now and I think I'm noticing some changes (for the better) to how task-lists show up, e.g. the sub-tasks in the issue header seems to have gone, but the "tracked by" in the child task is still there.

There's also overlap now between parent issues (which you can now group-by and slice-by in project views) and Milestones as a mechanism for grouping issues. The biggest differences being:

• Milestones are per repo, parent issues can be in any repo relative to children.
• "You can add up to fifty sub-issues per parent issue and create up to eight levels of nested sub-issues." vs many more issues per milestone.

[njzjz]

Update: We now have the beta enabled and I can confirm that sub-issues can be cross-repo.

Although the sub-issues can be cross-repo, I found the UI doesn't show the repo name.

[evi-liu]

Yes, as you mentioned, sub-issues can be cross-repo. Moving forward, we would also encourage you to migrate all content from tasklists to sub-issues, since sub-issues is our officially supported hierarchy solution moving forward.

[simensol]

The parent issue title is not parsed correctly in table view, as text wrapped in backticks (`) isn’t rendered as code:

[evi-liu]

Thanks for reporting! This is a known bug, and we have it in our backlog to fix soon.

[alexanderniebuhr]

One benefit of Tasklists was that you can track one issue in multiple "parent" issues, going back to only allow one parent issue is not great. Would love to see that an issue can have n parent issues.

[probitcarwyn]

The group-by/slice-by parent that you can do in projects now I guess would need to cluster by common parents a bit like issues with multiple assignees does, or otherwise show the issue multiple times?

[evi-liu]

@alexanderniebuhr Would love to hear more about this! What are you common use cases for having multiple parent issues?

[dylanpiera]

I'm a little surprised that PRs can't be added as sub-issues. I mean I suppose it's in the name sub-issues, but especially when it comes to project views, it feels like it'd be very fitting for the PRs to be located alongside/as a sub of the issue they're closing.

[evi-liu]

Thanks for the feedback, @dylanpiera! This is something we're monitoring feedback on during the public preview period.

[CoderNumber1]

It doesn't look like sub-issue creation allows for selecting an issue template/form. Is that something being considered?

[alexanderniebuhr]

I think I saw a select field when creating a new sub-issue, however not sure if that allows to choose from all templates.

[evi-liu]

When creating a sub-issue, you should be prompted to select the template/form based on the repository selected. Is it possible you're selecting a repository that doesn't have any associated templates or forms?

[khvn26]

I'd love to be able to see repo names in sub-issue lists.

[joefitzgerald]

I commonly create "roadmap" issues that contain a variety of "issues" which are really sub-issues. It is incredibly productive to use - [ ] syntax to rough out the list, and then create the issues from the roadmap issue. However, there appears to be no shortcut to do this as sub-issues instead of standalone issues.

Proposal: provide a mechanism for me to rough out an issues list like so, and then create sub issues from them instead of issues.
Proposal: provide a mechanism to bulk-add issues that are mentioned in an issue's description as sub issues, similar to the way you can "create issue".

- [ ] issue 1
- [ ] issue 2
- [ ] issue 3

[MarkBennett]

I'd add to this, that it would be great if there was a blank task field at the bottom of the list that I could use to quickly add tasks in a meeting or when brainstorming like you say, then I could convert them to issues and add details later.

[thompson-shaun]

This was one of the nice use cases with the [tasklist] beta feature.

Along with being able to reference PRs noted by https://github.com/orgs/community/discussions/139932#discussioncomment-10821434

[kressaty]

First of all, THANK YOU. SO awesome.

One thing - I love that I can link existing issues to parents/children. That said, it would be awesome if, when I choose link existing, I could just paste in the link to the issue (either full GitHub url or org/repo#xx) and it surfaces that immediately (or just saves). Lots of times I have the link handy from another tab/location and this would make navigating that much easier.

[mitchellh]

I'd find it useful to be able to configure the filter for the default issue list and count. I'd like to be able to omit issues with a parent (sub-issues) from the default view. Using sub-issues as a way to build up the tasks for a larger feature is something useful, but it's very noisy to have a lot of sub-issues polluting the default view. At the same time, it's very useful to have them show up in search and have their own issues for implementation discussion.

[VincentVerweij]

When I am inside a parent issue, and I would like to add sub-issues, I have the option to click Create sub-issue which gives me the option Add existing issue. In there I can type to search for issues.
Now, the thing is that when I click on an issue, the dialog closes. It would be nice if I could add multiple in one row. At the moment I have to click the Create sub-issue button again, type in my search, and click, and this is repeated for the amount of sub-issues that I would like to add.

[VincentVerweij]

I just found a quicker way of achieving this for now. When opening up a project, you can add the parent issue as a column. And then you are able to quickly copy/paste from one row to (many) other(s).