Skip to main content
A sub-issue is a full issue with one parent. It keeps its own status, assignees, project, milestone, dates and Activity. Use children for the deliverables inside one piece of work. Use a milestone for a phase or dated checkpoint, and a checklist subtask for a small step.

​
Plan children

Open the parent issue and use Add sub-issue or Attach existing. A new child inherits the parent’s project, milestone and team unless you choose another value. Children can span projects in the same workspace. You must be able to edit the child and both old and new parents when you change the link. Only one level is supported: a child cannot also have children. The board shows a done/total rollup and parent links. Use Hide sub-issues to focus on parents. Read counts and child lists include only work you can access. Parent archive or deletion detaches children; it does not delete them. Recurring parents do not copy children to the next occurrence.

​
Close a parent with open children

Choose a done column for the parent. The close dialog requires one decision:
  • Close open sub-issues: choose a done target for every child project.
  • Detach open sub-issues and leave them open: keep their status unchanged.
Already done children stay attached. The save validates edit access to every issue that changes and all selected columns before applying the changes. A stale column or missing permission rejects the entire close operation.

​
Enable automatic close

Automatic parent close is off by default. In Project Settings > Sub-issue close rules, a project administrator can enable Automatically close parents and choose both:
  • A Parent done column from the project’s done columns.
  • A Parent reopen fallback from the project’s not-done columns.
When the final child finishes, the parent is ready to close. With automatic close enabled and current edit access, the parent moves to the selected done column. If the actor cannot edit the parent, the child still completes and the parent remains for action. When a child reopens, an automatically closed parent returns to its previous column if it still exists, otherwise to its saved reopen fallback. If no valid reopen target remains or the actor lacks permission, the parent needs review. A manually closed parent remains closed and is flagged when children reopen. Readiness is also recalculated when children are archived, restored or deleted, and when a workflow change affects which children count as done. Automatic parent changes still require the current actor’s edit access. Existing recurrence completion restrictions apply to children closed with a parent and to automatic parent closes. A rejected collateral transition rolls back the whole operation.

​
Work through agent tools

To close children instead, use --open-children-action close and --child-done-columns '[{"project_id":"PROJECT_UUID","column_id":"DONE_COLUMN_UUID"}]'. Choose an explicit target for each changed child project, including the parent’s project. Projectless children use project_id: null, column_id: null, and an explicit status: "done" or "cancelled". Full and public MCP offer atoll_get_sub_issue_policy and atoll_set_sub_issue_policy. atoll_update_issue accepts open_children_action and child_done_columns. Discovery does not grant write access. See the API fields and webhook contract.