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.

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

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

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

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

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

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

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

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

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

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.

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

[dussab]

The new subissue support is great but it would even better if sub issues could point to both repos within and outside a GitHub organization. A common use case for companies doing open source is that they will create user stories in their corporate Github organization that points to both internal Github repos (e.g. frontend) and external Github organization's repos (e.g open sourced core components).

If i create a sub issue, I'm able to bring up a remote Github organization's repository issue template but I'm unable to actually create a sub-issue as it fails with a graphql error.

Thanks for the consideration!

[lchavey]

Can we get our task functionality added back to the sub issues

• change the title of the sub issues sections
• have multiple sub issues sections
• add text as a taks

[piotrooo]

Scenario:

• We have a repository named org/issues-hub
• In this repository, we have roadmap issues (epics)
• Each epic may have issues related to different, other repositories
• These repositories have the add-to-project.yml workflow, which uses a shared workflow org/github-internals/.github/workflows/org-add-to-project.yml@main
• This shared workflow utilizes the actions/add-to-project action to add issues to the project

When creating issues, the following error occurs:

Run actions/[email protected]
Creating project item
Error: Request failed due to following response errors:
 - Resource not accessible by integration

[Aarbel]

Question: would it be possible to assign people on sub-issues, directly for issue ? (when clicking on avatar)

[CalvinWilkinson]

I like this idea. This way we don't have to navigate to each issue separately.

[Aarbel]

Question: will it be possible to convert a checkbox as a sub-issue ?

[danemacmillan]

https://github.com/orgs/community/discussions/139932#discussioncomment-10822896

[CalvinWilkinson]

I seen that this new sub-issues feature will be replacing the task list feature currently in beta?

I don't know if we should get rid of the beta task lists feature. It is very easy to add more or delete tasks without having to go to edit and deal with markdown directly. The visual aspect of it is also appealing.

[dequejenn]

I agree! I am using both. Sub issues is for parent>child relationships (like an epic and its tickets). Tasklists I am using for blockers and dependencies - so within an epic, I can quickly on each ticket how many other tickets are still blocking it from being able to be picked up.

[michalludwik]

I just wanted to say that I love you guys for adding subitems feature.

Sincerely
Mike

[ewoutkramer]

I cannot seem to type an issue number in the right format to use it with parent: in the search bar. I think you have to include the repo name, and a slash, maybe the #, etc. I keep on forgetting. Would it be possible to display a useful help message, instead of the number just turning yellow?

[evi-liu]

Hi @ewoutkramer, we're currently working on building suggestions for this filter to make it easier. In the meantime, the correct format is parent-issue:"org/owner#X"

[KalebAxon]

When I try to add parents or sub-issues, I am only able to add issues within the same repo. This is an unfortunate limitation, severely limiting the feature's usefulness.

EDIT So, scrolling through this thread I found the explanation of how to do this. The UI is..... unintuitive. 🤷‍♂️

[gak]

Nice and fast. Love the shortcuts.

• Would be handy to be able to close sub tasks in the parent view.
• A keyboard shortcut for toggling "Create more" would be great.

[brunerae]

This looks fabulous so far - thank you for all of your hard work! I'd love the ability to further customize the appearance of sub-Issue lists in Parent Issues. Some things I'm interested in:

Grouping Sub-Issues into multiple lists
Ideally being able to customize the list name as well.

Seeing more Sub-Issue metadata in the Sub-Issue list:

• Repository
• Status
• Sprint
• Other custom fields

Thank you again!!

[theunrepentantgeek]

Is there a way to turn off sub-issues for a specific repo? I looked under settings, but the only option there is to turn off issues entirely.

[dequejenn]

Definitely missing seeing the repo name and labels like the tasklists do. Our epics cover many repos and often it is very similar titles (i.e. creating an api endpoint and a proxy for that endpoint in our customer facing repo). Very difficult to tell which is which without seeing the repo name.

[dequejenn]

Not sure if this is the correct place for this feedback, but now that I am using parent/sub issues (epics) I need to be able to order them when viewing their individual sub-issues (slicing or grouping issues by parent issue). Is there a way to set the "order by" of slices and/or groups? When slicing (or grouping) by parent, I need my important epics at top and completed epics at bottom or else over time this get really messy. I don't mind making an ordering field in my project but can't figure out how to make the slices/groups obey it, instead of just the tickets. Any ideas on how I can accomplish this?

[RodrigoHamuy]

I would prefer if sub-issues is integrated into the Tasklists format already implemented, rather than creating a new format.

Features I'm missing that exist in Tasklists but not in sub-issues:

• Add items using markdown (- [ ] Anything).
• This makes it easy to bulk create items.
• GH UI lets you convert checkbox items into a ticket.
• You can group things via simple markdown (eg: add # Titles in between).
• Easy to move up/down the description lists.

This is what I've been using so far, since GH already provides this functionality, I don't want to migrate to a new data layout system that also is lacking features like grouping, while I already had that sorted.

For context, this is what I mean, in any Ticket I can do this:

Title: Button

# Look & Feel

- [ ] Pick text font
- [ ] Pick colour

# Functionality

- [ ] Press on click
- [ ] Press on enter

GH UI then lets you convert each one of these into tickets, so later it looks like this:

# Look & Feel

- [ ] #2
- [ ] #3

# Functionality

- [ ] #4
- [ ] #5

And whenever those tickets are completed, GH automates ticking them.

So you were already 90% there, just add the new features there instead of creating a new thing.

For my particular case, all that is missing is progress visibility Project view, which is supported by sub-issues.

---

Related:

• Bulk add/edit/delete: https://github.com/orgs/community/discussions/139932#discussioncomment-10822896
• Multiple parents: https://github.com/orgs/community/discussions/139932#discussioncomment-10819774
• Convert tasks to sub-issues: https://github.com/orgs/community/discussions/139932#discussioncomment-10831726
• Support sub-issues that aren't issues yet https://github.com/orgs/community/discussions/139932#discussioncomment-10877891