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: 100
• 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.

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

[KalebAxon]

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

How did you get this to work? When I try to add a parent to an existing issue, only the issues within the same repo are available to me.

[fmagarrotebridge]

Poderia ter na parte de subissues, os status e a coluna que constam cada uma delas

[Maochengang]

five qubits built in the circuits, but the function of SparsePauliOp is representing IIZZ in the code which just has four qubits
web:https://learning.quantum.ibm.com/course/variational-algorithm-design/ansatze-and-variational-forms

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

[TIsmach]

This would be a game changer for us!

We use issues to document and keep track of client requests.
Often clients will request the same feature - we'd like to see multiple parent issues for one feature

In all honesty, I'd love a way to create a custom field with multi-select capabilities.
This way I can create a separate column titled "Client" and apply it to many issues - basically another type of label - just like the new "Issue Type" feature!

[CalvinWilkinson]

To be honest, I am trying to understand what the difference between a parent or child issue really is for.

Does the intent of a parent relationship mean that it is a dependency and needs to be completed first? I feel like can use a sub-issue to mean a dependency as well.

[stherold]

What are you common use cases for having multiple parent issues?

The dependency example was the first use case that came to my mind when I saw we only have one parent here.

Having multiple parents could enable advanced features like:

• making one parent the tracking issue aka Epic
• making other parent issues dependencies. to make this possible it would require a specific type (yes you introduced that already) to mark an issue as Epic (works already) and another one marking it as Dependency. This requires to add multiple types for an issue since an issue can be Parent/Epic and Dependency at the same time.

I know we go a little bit in the Jira direction here but that one would enable new features like blocking dependant issues as long as it has unclosed dependencies. Right now we go the lightweight way and define dependencies using a task list on top of the issue description.

[probitcarwyn]

To try and give a concrete example. We have a pile of issues that relate to a product orientated decision to improve software - e.g. improve logging, that has a sub-issue that related to centralising and protecting logs. This bit of the tree also relates directly to a compliance need that we learned about after the logging improvement epic started. It's useful to associate the centralised logging with the epic and the compliance issue. Two different sources for the same need. Not all logging improvement are a compliance related thing, and not all compliance tasks are logging. There are two roots to the motivation for a common subtree.

[jaschaio]

• Parents are unique ( an issue can only have one parent)

I also find it quite limiting to only be able to associate a single issue with one parent max.

I use parent issues mostly to categorize "big" features / products within our repository. But it could also be a huge task list, like "refactoring payment integrations".

So a single issue like "Refactor Stripe" might be associated with the parent issue "Payments" (which is the product where we are tracking different payment related features) but at the same time should also be associated with the "Refactoring payment integrations" issue where we would track all payment integrations including this one that need to be refactored.

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

[jhrmnn]

In our team we also think that for light-weight PRs having to create a separate issue just to track it in the parent issue is an unnecessary and distracting overhead.

[probitcarwyn]

PRs can already be linked to issues, indeed even cross-repo, via the "Development" section.

I suppose a valid question is whether there's a need for two different ways to relate PRs to issues? I'd prefer a more unified version of "Relationships".

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

[khvn26]

Here's an even better example — it's pretty obvious when you look at it:

[TWiStErRob]

@evi-liu the balance could be: show them if there's more than one, but hide if all are the same repo as the parent issue?

[EagleElijah]

Everything will be good.

[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

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

[Herostwist]

I really like the sub-issue feature but his is my biggest annoyance. Converting a task list item into an issue automatically makes the new issue "tracked by" the parent ticket but doesn't make it a sub-issue of the parent, which seems like an obvious thing it should do. Having to manually then add the new issue as a child is tedious.

[tobz-nz]

I really liked the simplicity of tasklists for this.
Mapping out the tasks that are required for the current ticket and checking them off as completed.

Creating whole new issues for each item seem like massive overkill.

I hope tasklists continue to be a thing (and it would be great to get the add button back or a create tasklist option included in the new sub-issue button/menu)

[EagleElijah]

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

I think that everything will be good.

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

[kressaty]

It does appear to be working now; initially it wouldn't "search" outside the issue's repo but all is good now!

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

[robotomarvin]

Wouldn't https://github.com/orgs/community/discussions/139932#discussioncomment-10835639 this somewhat ease the migration? Just adjust the markdown and be done?

[dequejenn]

I vote to keep tasklists in addition to sub-issues! They serve different purposes. Tasklists don't need to be issues. I use tasklists for brainstorming when creating a ticket or reminding me what needs to be done - like "make feature flag ticket", "make qa ticket", "get tech lead to fill out technical implementation section", etc. I have also used them to list out which issues are blocking this issue and what issues is this issue blocking. I liked that I didn't need to hit "edit" and find the list in the md each time to add another thing - the WYSIWYG of the tasklist is the part I enjoyed most. Super quick to add a note without having to switch to edit mode.

Alternatively having a UI like google docs would also solve this - where you can just type in the rendered description instead of having to switch to an edit mode, search around md code to find the place you are looking for and then save it to see if the md you added looks ok. I know most people using github are coders but as a product owner, I am the one creating the issues and not a coder so having the option of a more user-friendly WYSIWYG would be amazing!

[dodyg]

I concur. Task list is very efficient to create because you don't have multiple forms to deal with. I just wish we have "Convert to Sub Issue" in addition to "Convert to Issue".

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

[matthewberry]

Really liking the beta!

I second CoderNumber1's comment above--while the full hierarchy would be great, expanded parent-issue filters would be a very powerful stopgap.

[sebastianarnold]

We are doing it the same way: tracking high-level Epics in a Roadmap board and doing the daily work with Issues in a Kanban board. Sub-issues have really transformed the way we can now interconnect these stories nicely, so thanks for all the great work you've put into this!

Following up on this thread, we have the same problem: nested sub-issues produce more swimlanes in Group By view than intended, and the important top-level Epics get lost in that view. I might suggest that you could offer "Top level parent issue" in the "Group By" selection, would that be a potential solution?

[theomichail]

Loving the feature so far! Was wondering if there's any update on this?

[pjniffersham]

+1, any chance this will ship in Q4?

[ashnwade]

I am new to the beta, but I love the suggestion from sebastianarnold. I would love to be able to group by "Top level parent issue." I am loving the new functionality. So far, this is the one thing that I would really love to see added/changed.

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

[TWiStErRob]

I run into this every time when linking a PR that fixes an issue. Even though I know that button is there, it feels counter-intuitive. I have the URL on the clipboard, and there's a textfield, I should be able to just paste it, but it doesn't work when the wrong repo is selected.

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

[bendrucker]

Enjoying sub-issues a lot!

I'd prefer if clicking the assignee icon brought up the control for changing the assignee. When a sub-issue is assigned, my avatar links to a search for all my assigned issues in the repo, which isn't especially useful. And then for unassigned issues, there's no click target.

I don't bother assigning most sub-issues if they're tracking my own tasks that I'll close with corresponding PRs. But if I am delegating sub-issues, an inline control would be a lot faster than opening the full issue page for each.

[evi-liu]

Good idea! We have this tracked in our backlog as a future improvement 👍

[kgryte]

It would be great if the max sub-issues limit were removed. For some of our work, we'd love the ability to have a single large task list (200-300 sub-issues), rather than have to split it up into nested levels.

[evi-liu]

The sub-issues limit will soon increase from 50 to 100. Hopefully, that'll help a bit even if it's not 200 yet.

[probitcarwyn]

This reminds me of other comments in this topic about the relationship between parent issues and milestones. Especially given the scope of parent issues being org level while mliestones are repo level.

I'm so far finding the limit of 50 not too bad, but 100 is welcome. It forces me to create another level of nesting to group related children. It's very useful to be able to batch change parents in the project table view to help with this.

[jhdub23]

Why does there have to be a sub-issue limit? Can this be unlimited? We just hit 50, and I can see us easily hitting 100, especially for long-running epics. This is important for enterprise scaling.

[stbrwe]

On the parent issue where the list of sub-issues is shown, I want to be able to filter out the closed issues (and it would be nice to have other filters as well). We have some parent issues that are "evergreen", with "housekeeping" type of issues, and as time goes the list of sub-issues under the parent issue will become very long. So to keep the list of relevant sub-issues manageable, it would be very nice to have a filter option on the list of sub issues.

[leavauchier]

In this same view, I'd find it useful to be able to choose some features of the sub-issues to display. For example I'd love to be able to see the estimates of all the sub-issues in a glance

[jhdub23]

Could this be handled through GitHub projects through an expandable/collapsible hierarchy? I'd love to be able to apply various filters within that hierarchy.

[Mykhol]

Love this feature, one really minor thing I'd love to see a change to is properly showing the status of a PR in the list:

These are currently open PRs but they look quite similar to the "draft" PR status, might be good to change these to the typical "open" color (theme dependent)

[abbluiz-userh]

Hi. About the sub-issues progress... I wonder if we could choose a status to determine if an issue is done instead of just closed issue being marked as done... on my workflow, a closed issue is only when the issue is in production environment, and sometimes that takes long... I would like to choose a custom status to determine if an subissue is done, such as reaching QA or STAGING environment (which in my case can be inferred by some status).

[probitcarwyn]

We're using Project "Status" fields, which by default are also the column indicators in the Board view for this.

What is missing from this approach though is a state machine to allow or disallow certain transitions (e.g. there's no enforcement of having to visit a column - QA being a good example.).

[abbluiz-userh]

@probitcarwyn I couldn't reproduce what you said. I mean, I thought the criteria to consider a sub issue as completed, is the issue being closed as completed (maybe even closed as not planned or just "closed"). If the last "status" is used for this (in my case the equivalent of "Done") it wouldn't be enough because maybe I want a previous status to consider the sub issue as completed, as we mentioned, status "QA" or any other status. Maybe my use case is super specific, but I think an issue can travel through a lot of status before getting closed, and we can't sense the real progress of the sub issues if we don't change the criteria

[AndreuCodina]

Managing dailies with Jira Cloud is easy because you see the User Stories and tasks in a single view. With GitHub projects and the board view you don't know what's the status of each task without entering in each US.

[matous-vrba]

Hi, how can we select which properties the sub-issues should inherit? Such as project, version and so on? Thanks

[wtf403]

Hi, I recently joined the waitlist for the public beta for my organization (buydry) but I haven’t received a confirmation email yet. Could you assist in enabling the feature to begin testing?
Sub-issues looks fantastic, I’m excited to try it out! 😻

[ncc-swann]

Hi.
I generally love sub-issues, so thank you!

I just encountered a strange behavior:

I had a sub-issue which I assigned a Milestone in order to see it in my Project Roadmap. The sub-issue did not show up. Is this intended?

I then removed the parent, thinking I was promoting the sub-issue to a "regular" issue and expecting to see it in my roadmap, but it did still not show up.

I tried removing and reapplying the Milestone without effect.

Edit:
And I just realized that is occurred because the sub-issue did not inherit the parent issue's Projects.

Is this desired? In this case it certainly felt weird.

[ncc-swann]

Hi again.

Another piece of feedback:

I was working on a sub-issue and realized I needed another sub-issue on the same parent - a sibling issue. I intuitively looked under Relationships to see if there might be a shortcut for this.

What do you think about having such a shortcut?

It's not like it would save me a lot of clicks, but intuitively it felt like it was missing in the context of parent-sub relationships.

[yumbrad]

I'm embarking on an attempt to bring a lot of our scattered feature planning into github and would love to test/use sub-issues for the task, any way I can get my access request granted? (haven't received an email yet - "ClassGenius" organization)

[savstars]

@evi-liu Is there an expected release date for this (that is, non-beta)? I do understand that this could be a moving target.

[li-mc]

Task lists could be used for issues linked across different organizations/suborganizations. Is there a plan to allow this for sub-issues? Seeing this fail with "A sub-issue must belong to the same organization or user as the parent".

[GeoJunkie]

Question: Why is the sub_issue_id required when adding a sub-issue in the REST API? Shouldn't that be getting returned instead of being provided?