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.

[probitcarwyn]

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.

I kind of like the "tracked by" feature from task lists that's still present in the current beta for task lists. Having something like this for cross-organisation references, as opposed to just notes in the issue history would be nice. The "checkbox" seems misleading in this context though as all I really need is a way to see what other global GH issues reference my issue, and/or have a nice UI cue to show links to other issues I might be tracking in a lightweight manner.

Unless GH really are thinking that parent/child will be possible cross-org? That would do it too, but would surely not scale.

[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?

[alexanderniebuhr]

@evi-liu Our use-case mostly consist when we have a repository (package) which is used in multiple other repositories (websites).. When we do track broader tasks for each website, we sometimes want to add an issue of the package to the website parent issues, so we can see it there, however the actual implementation will be happening in the package. We don't want to create duplicated issues for that, so in the past we just added it to multiple tasklists.. To summarize the use is to get more visibility from different collective issues, which can live in the same parent repository or in multiple. Hope that helps :)

[TWiStErRob]

@evi-liu we have a similar one:

• we track objectives and key results as issues. Key results have a single objective parent, so far so good.
• we track epics with parent key results. There can be easily epics that have wide-spread effects contributing to multiple key results.

An example: adding cache to a project. It affects KRs in both "developer experience" and "release cadence" objectives.

[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.

[probitcarwyn]

This debate comes up a lot for us, the ability to put so much detail in PRs means they can end up also tracking work, especially if the PR needs lots of changes. The key difference being that issues happen before work, PR's usually only appear after work is close to ending (in theory).

[thompson-shaun]

We frequently get OSS contributions that start as PRs. This does encourage tracking PRs much like issues.

[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?

[CoderNumber1]

Yes, I see that now, sorry. I was getting ahead of myself reading the documentation before I actually had a chance to try it out. Fantastic, it's exactly what I was hoping to see.

[khvn26]

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

[evi-liu]

Noted! We're trying to find the right balance between keeping the sub-issues decluttered and showing metadata, so good to know that repo names is important. I'll keep monitoring to see how strongly others need this as well.

[bohdan-shulha]

Agree.

This looks like a mess without repo names.

[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

[evi-liu]

Thanks for the feedback, y'all! This is a common feature request, and we are looking to bring markdown checklist to sub-issues conversion capability!

[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.

[evi-liu]

Hi @kressaty, this should already be working, where you're able to copy a URL to add as a sub-issue. Could you send a screenshot or gif of this not working? We can take a look.

[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.

[probitcarwyn]

We've been using two boards for this kind of separation, parents on one higher level planning board, with sub-issues on the "work" board. Related to your comment, being able to manage which project sub-issues are created on (whether same as parent or not) would be useful.

[evi-liu]

I'd like to be able to omit issues with a parent

Try -has:parent-issue - that should get you your desired filter!

[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).

[lkiii]

I would really like to have this option enabled on the Project only issues. The use case is to have a cross repo issue as a parent which should not get converted to the repo issue. Now sub-isssues are only available in the repo issues

[probitcarwyn]

We have a dedicated no-code repo that we use to "own" the parent issues.

[TWiStErRob]

Please allow migration/conversion of Tasks lists to parent/sub-issues!

It's quite tedious to manually move every single issue to have a parent relationship.

Related: https://github.com/orgs/community/discussions/39106#discussioncomment-10831691

[evi-liu]

Apologies for the tedious manual conversion. To be super transparent, we've seen tasklists usage steadily decline while sub-issues continues to grow. Consequently, it's looking less and less worth it for us to invest in a tasklists migration path (compared to improving other sub-issues enhancements, such as other top voted requested mentioned above). For now, I'd recommend using the keyboard shortcuts to help speed up the migration process.

[CoderNumber1]

I like that I can group issues by parent issue on project boards; but is there a way to control which parent issues are allowed to be part of that top-level grouping? Working off of https://github.com/orgs/community/discussions/139932#discussioncomment-10817810 I am a big fan of the idea to use a top-level parent issue as a sort of cross repo milestone. Normally the way I lay out a project I have this sort of hierarchy:

• Milestone (top-level Project type issue in this case)
  • User Stories
    • Work Item1
    • Work Item2
  • Bug Report
    • Work Item 3
    • Work Item 4

Currently I use milestones as best I can to track a top-level status of projects across my team on a single project board. I was hoping to do the same thing with a top-level project type issue and be able to display a hierarchy of: project issue -> story/bug -> work items. However because the stories and bugs themselves are parent issues I end up with them being top-level groups on the board:

I would much rather only see the parent issues grouped by those that are Project type issues here, and then be able to expand those to show the immediate children (story/bug), and possibly even further expand to display work items grouped by story/bug.

[CoderNumber1]

Understanding that the nesting could get out of hand, a nice alternative might be to be able to slice by parent issues (only of the Project type), then then group in the main view by those issues which are of type Story or Bug.

[probitcarwyn]

We've ended up putting the top level parent (theme/epic) issues on another project board, often in roadmap view, with the sub-issues on the day to day work boards (kanban-like).

[CoderNumber1]

That's similar to something I'm doing now. It sort of makes for extra work to keep the status fields updated on each board, since those fields aren't shared though. I was hoping to be able to consolidate some of our project boards this way. If we could control what options that slicing and grouping is done by independently, that would be extremely helpful I think.

Something else that might be very helpful is extending the parent-issue: filtering to things like type, label, etc. E.G. parent-issue-type:Epic

[evi-liu]

Being able to show the full hierarchy tree in Projects is one of our top requests. It's on our roadmap, and we're looking into how we can make it a reality. It's quite the engineering lift on our end, so appreciate your patience!

[CoderNumber1]

As I've thought on it and experimented today, I think more important in the short term than showing the full hierarchy (especially understanding the effort required for that) would be expanding the parent-issue filters. If for instance I could apply parent-issue-type:Epic or parent-issue-label:foo that would go a long way.

[baynezy]

You can create a sub-issue in a different repository, but you cannot add an existing one from the create sub-issue drop down when viewing an issue. This is a bit limiting.

[evi-liu]

When selecting Add existing issue for sub-issues, you can change the repository you are selecting from with this button:

[baynezy]

Thanks. It's not super intuitive, but I can do what I want now.

[CoderNumber1]

When clicking the Create sub-issue button, the scroll bar disappears. When selecting lists like issue type and label on the create sub-issue modal, the lists are cut off:

[evi-liu]

This is a known bug, and we are looking to resolve it!

[pickleshy]

First – WOW I LOVE IT. I've been missing nested issues since using Fogbugz over a decade ago. Thank you.

I would love to be able to see Github Project issue statuses surfaced on sub-issue lists. The binary open/closed tells me a lot, but not enough, about the work to be done. "Open" can mean anything from "Todo" to "In review" – so it would be helpful to see the rest of our workflow reflected at this high-level view.

[marioanloru]

First of all, this update is nuts!

I have an use case it's not clear to me how should I be doing it; I group tasks by priority to see how critical they are, and usually slice by asignees. It seems subtasks do not show on a list view if group by is different from "parent issue", is this something on the TODO list?

Will it be possible to group by priority and see on the resulting list subtask shown hierarchically?

Would be this image, but with "Sub-issues" title being one of a priority kind, eg "P0" but on projects list view

Thanks!

[damianh]

Is it possible to enable/disable this feature on a per-repository basis? We have some repositories where simple issues without sub-issue functionality is desirable.

[sid-2098]

The parent issue doesn't support more than 50 sub-issue. Is it possible to add 175 sub-issues to parent issue?

Use case:
I have a Epic Parent with more than 175 task issues created in it. I want to attach the parent to all the task. Due to current limit of 50, I am not able to add parent to all the task. Is it possible to increase the limit to 200?

Also is there a way by which i can add sub issue via markdown?