NXS GitHub Create Task
Create GitHub issues from TASK-???.md files in a target folder.
Usage
python ./scripts/create_gh_issues.py <target_folder> [--dry-run] [--no-project]
Arguments:
target_folder- Directory containing TASK-???.md files--dry-run- Preview what would be created without making API calls--no-project- Skip adding issues to any project
Task File Format
Each TASK-???.md file should have YAML frontmatter:
---
title: Implement user authentication
labels: [enhancement, backend]
parent: #42
project: "acme-corp/backend-roadmap"
---
## Description
Task body content goes here. This becomes the issue body.
Frontmatter fields:
| Field | Required | Description |
|---|---|---|
title |
Yes | Issue title |
labels |
No | Array of GitHub labels: [label1, label2, ...] |
parent |
No | Parent issue reference (#42 or full URL) |
project |
No | GitHub project to add the issue to. Supports: owner/number (e.g., my-org/1), number (uses current repo's owner), or project title. If omitted, auto-discovers from repository. |
Workflow
- Script finds all
TASK-???.mdfiles matching the pattern - For each file:
- Parses YAML frontmatter to extract title, labels, parent, project
- Creates temp file with body content (frontmatter stripped)
- Runs
gh issue create --title <title> --label <label1> --label <label2> ... --body-file <temp> - Adds issue to the specified project (or auto-discovered project from repo)
- If parent specified, creates sub-issue relationship via
gh api - Deletes temp file
Project Resolution
The script determines which project to use in this order:
- Frontmatter
projectattribute - If specified in the task file, use this project - Repository project - If no
projectattribute, auto-discover from the repository's linked projects - No project - If neither is found (or
--no-projectflag is set), skip project assignment
Prerequisites
ghCLI installed and authenticated- For project integration:
gh auth login --scopes 'project' - Repository context (run from within a git repo or use
gh repo set-default)
Examples
# Preview what will be created
python ./scripts/create_gh_issues.py ./tasks --dry-run
# Create the issues (uses project from frontmatter or auto-discovers)
python ./scripts/create_gh_issues.py ./tasks
# Create issues without adding to any project
python ./scripts/create_gh_issues.py ./tasks --no-project