Manage GitHub sub-issues (child issues) using native gh CLI commands (v2.94.0+).
Prerequisites
Before using any sub-issue commands, verify the gh CLI is v2.94.0 or newer:
gh --version
If the version is older than 2.94.0, the native sub-issue flags (--parent, --add-sub-issue, --remove-sub-issue, --remove-parent) will not be available. In that case, advise the user to upgrade gh before proceeding.
Commands
Create a new sub-issue
Create a new issue directly linked as a child of a parent issue:
gh issue create --parent <parent-issue> --title "<title>" --body "<body>" --repo posit-dev/py-shiny
Flags:
--parent— Parent issue number or URL (required for sub-issue linking)--title— Title for new sub-issue (required)--body— Body text for the sub-issue--label— Comma-separated labels--assignee— Comma-separated usernames--milestone— Milestone name or number--project— Project to add the issue to
Add an existing issue as a sub-issue
gh issue edit <parent-issue> --add-sub-issue <child-issue> --repo posit-dev/py-shiny
Set or change the parent of an issue
gh issue edit <child-issue> --parent <parent-issue> --repo posit-dev/py-shiny
List sub-issues of a parent
gh issue view <parent-issue> --json subIssues,subIssuesSummary --repo posit-dev/py-shiny
Remove a sub-issue link
gh issue edit <parent-issue> --remove-sub-issue <child-issue> --repo posit-dev/py-shiny
Remove parent from an issue
gh issue edit <child-issue> --remove-parent --repo posit-dev/py-shiny
Usage Notes
- Always include
--repo posit-dev/py-shinyto ensure correct repository context - When creating multiple sub-issues, create them sequentially to avoid rate limiting
- Use
--bodywith heredoc for multi-line descriptions:
gh issue create --parent 123 --title "My issue" --body "$(cat <<'EOF'
Description here.
**Acceptance criteria:**
1. First item
2. Second item
EOF
)" --repo posit-dev/py-shiny
- Reference the parent issue in the body for context (e.g., "Part of #123")