{"id":29895565,"url":"https://github.com/d-oit/gh-sub-issues","last_synced_at":"2025-10-11T06:06:00.749Z","repository":{"id":306956608,"uuid":"1027838136","full_name":"d-oit/gh-sub-issues","owner":"d-oit","description":"A robust tool for managing hierarchical issues with GitHub Projects using the official CLI.","archived":false,"fork":false,"pushed_at":"2025-08-18T07:08:00.000Z","size":251,"stargazers_count":1,"open_issues_count":17,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-18T09:16:40.410Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/d-oit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-28T15:55:38.000Z","updated_at":"2025-08-01T07:46:35.000Z","dependencies_parsed_at":"2025-07-28T17:44:42.966Z","dependency_job_id":"11685230-b67d-414d-9318-149849fb6055","html_url":"https://github.com/d-oit/gh-sub-issues","commit_stats":null,"previous_names":["d-oit/gh-sub-issues"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/d-oit/gh-sub-issues","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-oit%2Fgh-sub-issues","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-oit%2Fgh-sub-issues/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-oit%2Fgh-sub-issues/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-oit%2Fgh-sub-issues/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/d-oit","download_url":"https://codeload.github.com/d-oit/gh-sub-issues/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-oit%2Fgh-sub-issues/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006448,"owners_count":26084105,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-01T07:21:02.446Z","updated_at":"2025-10-11T06:06:00.735Z","avatar_url":"https://github.com/d-oit.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub Issue Manager\n\nA robust tool for managing hierarchical issues with GitHub Projects using the official CLI.\n\n## Features\n\n- ✅ **Automates sub-issue creation** - Handles GitHub's complex GraphQL API requirements since sub-issues aren't directly supported in the CLI\n- ✅ **Simplifies hierarchical workflows** - Single command creates both parent and child issues with proper linking\n- ✅ **Automatic project board linking** with configurable project URLs\n- ✅ **Optional comprehensive logging** - Track operations, debug issues, and monitor performance\n- ✅ **Environment-based configuration** via `.env` files\n- ✅ **CLI-based workflow** with comprehensive error handling\n- ✅ **Input validation** with whitespace and empty argument checking\n- ✅ **Dependency verification** for required tools (gh, jq)\n- ✅ **Graceful error handling** with detailed error messages\n- ✅ **Automated release management** - Version bumping, changelog generation, and GitHub releases\n- ✅ **GitHub Actions workflows** - Automated CI/CD, issue management, and maintenance\n- ✅ **Comprehensive testing suite** - Unit tests, integration tests, and release validation\n\n## Prerequisites\n\n- **GitHub CLI v2.40+** with sub-issues feature support\n- **jq** for JSON processing\n- **Git repository** with GitHub remote configured\n- **GitHub authentication** (`gh auth login`)\n- **bash** shell environment (Linux, macOS, or WSL on Windows)\n- **bc** calculator for mathematical operations (used in release management)\n\n## Installation\n\n### Quick Start\n\n1. **Clone the repository:**\n\n   ```bash\n   git clone https://github.com/d-oit/gh-sub-issues.git\n   cd gh-sub-issues\n   ```\n\n2. **Install dependencies:**\n\n   ```bash\n   # Install GitHub CLI\n   curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg\n   echo \"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main\" | sudo tee /etc/apt/sources.list.d/github-cli.list \u003e /dev/null\n   sudo apt update\n   sudo apt install gh\n\n   # Install jq and bc\n   sudo apt-get install jq bc\n\n   # Authenticate with GitHub\n   gh auth login\n   ```\n\n3. **Make scripts executable:**\n\n   ```bash\n   chmod +x gh-issue-manager.sh\n   ```\n\n4. **Verify installation:**\n   ```bash\n   ./gh-issue-manager.sh --help\n   ```\n\n### Configuration\n\n1. **Configure environment (optional):**\n   ```bash\n   cp .env.example .env\n   # Edit .env to set PROJECT_URL if using project boards\n   ```\n\n## Automated Workflows\n\nThis project includes comprehensive GitHub Actions workflows for automation:\n\n### 🚀 Release Automation (`release.yml`)\n\n- **Manual trigger** with version bump options (patch/minor/major)\n- **Pre-release support** for alpha/beta versions\n- **Automated testing** before release creation\n- **Issue closure** for items marked \"fixed-in-next-release\"\n- **Project board updates**\n\n**Usage:**\n\n1. Go to Actions → Automated Release\n2. Click \"Run workflow\"\n3. Select version bump type and options\n4. The workflow will test, create release, and close issues\n\n### 🔄 Continuous Integration (`ci.yml`)\n\n- **Automated testing** on push/PR to main branch\n- **Shellcheck validation** for code quality\n- **Security scanning** for potential vulnerabilities\n- **Dry-run release testing**\n\n### 🤖 Issue Automation (`issue-automation.yml`)\n\n- **Auto-labeling** based on issue title/content\n- **Release tracking** for issues tagged with release labels\n- **Sub-issue creation** via comments (`/create-sub-issues`)\n- **Project board management**\n\n### 🧹 Scheduled Maintenance (`scheduled-maintenance.yml`)\n\n- **Weekly maintenance** runs every Sunday\n- **Stale issue management** (60+ days inactive)\n- **Dependency updates** checking\n- **Maintenance reports** generation\n\n### 🔀 Auto-merge (`auto-merge.yml`)\n\n- **Automatic PR merging** when labeled \"auto-merge\"\n- **CI validation** before merge\n- **Failure notifications**\n\n## Usage\n\n### GitHub Wizard (Interactive Interface)\n\nThe GitHub Wizard provides an interactive command-line interface for managing GitHub issues, releases, and project workflows:\n\n```bash\n# Run the interactive wizard\n./gh-wizard.sh\n\n# Run with debug mode enabled\n./gh-wizard.sh --debug\n\n# Run with verbose output\n./gh-wizard.sh --verbose\n\n# Run with performance monitoring\n./gh-wizard.sh --performance\n\n# Custom logging configuration\n./gh-wizard.sh --log-level DEBUG --log-file ./debug.log\n\n# Show help\n./gh-wizard.sh --help\n```\n\n#### Wizard Command Line Options\n\n- `--debug` / `-d` - Enable debug mode (verbose logging and output)\n- `--verbose` / `-v` - Enable verbose output\n- `--performance` / `-p` - Enable performance monitoring\n- `--log-level LEVEL` - Set log level (DEBUG, INFO, WARN, ERROR)\n- `--log-file PATH` - Set log file path\n- `--help` / `-h` - Show help message\n\n### Direct Script Usage (gh-issue-manager.sh)\n\n```bash\n./gh-issue-manager.sh \"Parent Title\" \"Parent Description\" \"Child Title\" \"Child Description\"\n```\n\n#### Example\n\n```bash\n./gh-issue-manager.sh \\\n  \"Implement User Authentication\" \\\n  \"Add OAuth2 authentication system with JWT tokens\" \\\n  \"Create Login API Endpoint\" \\\n  \"Implement POST /api/auth/login endpoint with validation\"\n```\n\n#### With Logging Enabled\n\n```bash\n# Enable logging with INFO level\nENABLE_LOGGING=true LOG_LEVEL=INFO ./gh-issue-manager.sh \\\n  \"Implement User Authentication\" \\\n  \"Add OAuth2 authentication system with JWT tokens\" \\\n  \"Create Login API Endpoint\" \\\n  \"Implement POST /api/auth/login endpoint with validation\"\n\n# Enable debug logging for troubleshooting\nENABLE_LOGGING=true LOG_LEVEL=DEBUG ./gh-issue-manager.sh \\\n  \"Debug Issue Creation\" \\\n  \"Test issue for debugging purposes\" \\\n  \"Debug Child Issue\" \\\n  \"Child issue for testing\"\n```\n\n## Configuration\n\n### Environment Variables (.env)\n\n```bash\n# Optional: Project board URL for automatic issue assignment\nPROJECT_URL=https://github.com/orgs/your-org/projects/1\n\n# Optional: GitHub token (usually not needed if gh CLI is authenticated)\nGITHUB_TOKEN=your_personal_access_token\n\n# Logging and Debug Configuration\nENABLE_LOGGING=true                    # Enable/disable logging (default: false)\nLOG_LEVEL=INFO                         # Log level: DEBUG, INFO, WARN, ERROR (default: INFO)\nLOG_FILE=./logs/gh-issue-manager.log   # Log file path (default: ./logs/gh-issue-manager.log)\nDEBUG_MODE=false                       # Enable debug mode (default: false)\nVERBOSE_MODE=false                     # Enable verbose mode (default: false)\nPERFORMANCE_MONITORING=false           # Enable performance monitoring (default: false)\nLOG_ROTATION_SIZE=10485760            # Log rotation size in bytes (default: 10MB)\nLOG_ROTATION_COUNT=5                  # Number of old logs to keep (default: 5)\n```\n\n### Project Board Setup\n\n1. Create a GitHub Project board\n2. Set up columns: **Backlog** → **In Progress** → **Done**\n3. Copy the project URL to your `.env` file\n4. Issues will be automatically added to the project\n\n## Logging and Debugging\n\nThe GitHub Issue Manager includes comprehensive logging and debugging capabilities to help with troubleshooting, monitoring, and audit trails.\n\n### Debug Mode\n\nEnable debug mode for comprehensive troubleshooting:\n\n```bash\n# Using the wizard with debug mode\n./gh-wizard.sh --debug\n\n# Using environment variables\nDEBUG_MODE=true ./gh-wizard.sh\n\n# Debug mode automatically enables:\n# - Verbose logging (DEBUG level)\n# - Verbose console output\n# - Performance monitoring\n# - Configuration dumps\n```\n\n### Verbose Mode\n\nEnable verbose output for detailed console information:\n\n```bash\n# Using the wizard with verbose mode\n./gh-wizard.sh --verbose\n\n# Using environment variables\nVERBOSE_MODE=true ./gh-wizard.sh\n```\n\n### Performance Monitoring\n\nMonitor GitHub API performance and detect slow operations:\n\n```bash\n# Using the wizard with performance monitoring\n./gh-wizard.sh --performance\n\n# Using environment variables\nPERFORMANCE_MONITORING=true ./gh-wizard.sh\n\n# Performance monitoring features:\n# - GitHub API call timing\n# - Slow operation detection (\u003e2s for API calls, \u003e5s for others)\n# - Performance warnings in logs and console\n```\n\n### Logging Configuration\n\nConfigure logging through environment variables or command-line options:\n\n```bash\n# Enable logging (default: false)\nENABLE_LOGGING=true\n\n# Set log level (default: INFO)\nLOG_LEVEL=DEBUG    # Most verbose: DEBUG, INFO, WARN, ERROR\nLOG_LEVEL=INFO     # Standard: INFO, WARN, ERROR\nLOG_LEVEL=WARN     # Warnings and errors only: WARN, ERROR\nLOG_LEVEL=ERROR    # Errors only: ERROR\n\n# Set log file path (default: ./logs/gh-issue-manager.log)\nLOG_FILE=./logs/gh-issue-manager.log\n\n# Command-line options (wizard only)\n./gh-wizard.sh --log-level DEBUG --log-file ./debug.log\n```\n\n### Log Rotation\n\nAutomatic log rotation prevents log files from growing too large:\n\n```bash\n# Configure log rotation\nLOG_ROTATION_SIZE=10485760    # 10MB (default)\nLOG_ROTATION_COUNT=5          # Keep 5 old logs (default)\n\n# Log files are rotated as:\n# - gh-issue-manager.log (current)\n# - gh-issue-manager.log.1 (previous)\n# - gh-issue-manager.log.2 (older)\n# - ... up to LOG_ROTATION_COUNT\n```\n\n### Log Levels\n\n- **DEBUG** - Detailed debugging information including API calls, timing, and internal operations\n- **INFO** - General operational information about successful operations and progress\n- **WARN** - Warning messages for non-critical issues (also output to console)\n- **ERROR** - Critical failures and errors (also output to console)\n\n### Log Format\n\n```\n[TIMESTAMP] [LEVEL] [FUNCTION] MESSAGE\n[2025-01-15 10:30:45] [INFO] [create_issues] Creating parent issue: 'Feature Implementation'\n[2025-01-15 10:30:46] [DEBUG] [create_issues] GitHub API call: gh issue create --title...\n[2025-01-15 10:30:47] [INFO] [create_issues] Parent issue created: #123\n[2025-01-15 10:30:48] [INFO] [create_issues] Execution time: 2.145s\n```\n\n### Usage Examples\n\n```bash\n# Basic logging - INFO level\nENABLE_LOGGING=true ./gh-issue-manager.sh \"Title\" \"Body\" \"Child\" \"Body\"\n\n# Debug logging for troubleshooting\nENABLE_LOGGING=true LOG_LEVEL=DEBUG ./gh-issue-manager.sh \"Title\" \"Body\" \"Child\" \"Body\"\n\n# Custom log file location\nENABLE_LOGGING=true LOG_FILE=/var/log/github-issues.log ./gh-issue-manager.sh \"Title\" \"Body\" \"Child\" \"Body\"\n\n# Set in .env file for persistent configuration\necho \"ENABLE_LOGGING=true\" \u003e\u003e .env\necho \"LOG_LEVEL=INFO\" \u003e\u003e .env\n./gh-issue-manager.sh \"Title\" \"Body\" \"Child\" \"Body\"\n```\n\n### What Gets Logged\n\n- **Function execution** - Entry, exit, and timing for all major functions\n- **GitHub API operations** - Issue creation, sub-issue linking, project assignments with performance monitoring\n- **Performance metrics** - Execution time for each operation and total runtime\n- **Error details** - Comprehensive error information with context\n- **Configuration loading** - Environment and .env file processing\n- **Validation results** - Input validation and dependency checks\n- **Menu navigation** - Wizard menu selections and navigation flow (wizard mode)\n- **User interactions** - Input validation and error handling (wizard mode)\n- **Debug information** - Detailed internal state and variable dumps (debug mode)\n\n### GitHub API Performance Monitoring\n\nEnhanced GitHub API wrappers provide detailed performance insights:\n\n```bash\n# API call wrappers with timing:\ngh_api_call \"user\" \"function_name\"           # General API calls\ngh_issue_call \"create\" \"function_name\"       # Issue operations\ngh_project_call \"item-add\" \"function_name\"   # Project operations\n\n# Performance warnings for slow operations:\n[2025-01-15 10:30:47] [WARN] [create_issues] SLOW OPERATION: GitHub API execution time: 3.245s (threshold: 2s)\n```\n\n### Log File Management\n\n- **Automatic directory creation** - Log directory created if it doesn't exist\n- **Append mode** - New executions append to existing log file\n- **Automatic rotation** - Logs rotate automatically when size limit is reached\n- **Cross-platform compatibility** - Works on Windows, Linux, and macOS\n\n```bash\n# Log rotation happens automatically, but you can also rotate manually:\nmv logs/gh-issue-manager.log logs/gh-issue-manager-$(date +%Y%m%d).log\n```\n\n## Error Handling\n\nThe script includes comprehensive error handling for common scenarios:\n\n- ❌ **Missing dependencies**: Checks for `gh` and `jq`\n- ❌ **Invalid arguments**: Validates all 4 required arguments\n- ❌ **Empty/whitespace arguments**: Rejects blank or whitespace-only inputs\n- ❌ **Repository context**: Ensures you're in a valid Git repository\n- ❌ **GitHub API failures**: Handles authentication and permission issues\n- ❌ **Project board errors**: Gracefully handles project assignment failures\n\n## Testing\n\nRun the comprehensive test suite:\n\n```bash\n# Run all tests\n./tests/run-all-tests.sh\n\n# Run specific test suites\n./tests/test-unit.sh              # Unit tests\n./tests/test-mocked-integration.sh # Mocked integration tests\n./tests/test-coverage.sh          # Coverage analysis\n```\n\n## Best Practices\n\n1. **Issue Hierarchy**: Uses official GitHub sub-issue relationships via GraphQL API\n2. **Project Organization**:\n   - Columns: Backlog → In Progress → Done\n   - Use metadata labels for filtering and automation\n3. **Automation Requirements**:\n   - GitHub CLI v2.40+ with `sub_issues` feature flag\n   - Personal access token needs `public_repo` or `repo` scope\n4. **Error Prevention**:\n   - Always run from within a Git repository\n   - Ensure GitHub CLI is authenticated\n   - Verify project URLs before use\n\n## Why This Script?\n\nGitHub's CLI (`gh`) doesn't natively support sub-issue creation. Without this script, you would need to manually:\n\n1. Create parent issue\n2. Create child issue\n3. Use GraphQL API directly to link them\n4. Handle API authentication and error checking\n5. Manage project board assignments separately\n\nThis script automates all these steps in a single command while ensuring:\n\n- ✅ Proper error handling at each stage\n- ✅ Input validation and sanitization\n- ✅ Environment configuration management\n- ✅ Project board integration\n\n## Technical Implementation\n\nUses GitHub's GraphQL API with `sub_issues` feature flag:\n\n```graphql\nmutation {\n  addSubIssue(input: { issueId: \"PARENT_ID\", subIssueId: \"CHILD_ID\" }) {\n    clientMutationId\n  }\n}\n```\n\n### Script Architecture\n\nThe script is modularized into testable functions:\n\n- `validate_input()` - Input validation and sanitization\n- `check_dependencies()` - Verify required tools are available\n- `load_environment()` - Load configuration from .env file\n- `get_repo_context()` - Extract repository information\n- `create_issues()` - Create parent and child issues\n- `link_sub_issue()` - Establish parent-child relationship\n- `add_to_project()` - Add issues to project board\n- `main()` - Orchestrate the complete workflow\n\n### API Requirements\n\n- **GitHub CLI v2.40+** with sub-issues feature support\n- **Personal access token** with `repo` scope (handled by gh CLI)\n- **GraphQL Features header**: `sub_issues` flag enabled automatically\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"Failed to get repository owner\"**\n\n   ```bash\n   # Ensure you're in a Git repository with GitHub remote\n   git remote -v\n   gh repo view  # Should show repository info\n   ```\n\n2. **\"Missing required dependencies\"**\n\n   ```bash\n   # Install missing tools\n   sudo apt install gh jq  # Ubuntu/Debian\n   brew install gh jq      # macOS\n   ```\n\n3. **\"Failed to create sub-issue relationship\"**\n\n   - Sub-issues feature may not be available for your repository\n   - Check GitHub CLI version: `gh --version`\n   - Ensure you have write permissions to the repository\n\n4. **\"Failed to add to project board\"**\n   - Verify PROJECT_URL in .env file\n   - Ensure you have admin access to the project\n   - Check project visibility settings\n\n### Debug Mode\n\nMultiple debugging approaches available:\n\n```bash\n# Method 1: Wizard debug mode (recommended)\n./gh-wizard.sh --debug\n\n# Method 2: Environment variable debug mode\nDEBUG_MODE=true ./gh-wizard.sh\n\n# Method 3: Direct script with debug logging\nENABLE_LOGGING=true LOG_LEVEL=DEBUG ./gh-issue-manager.sh \"Parent\" \"Body\" \"Child\" \"Body\"\n\n# Method 4: Shell debug mode (advanced)\nset -x  # Enable debug mode\n./gh-issue-manager.sh \"Parent\" \"Body\" \"Child\" \"Body\"\nset +x  # Disable debug mode\n\n# Method 5: Combined approaches\nset -x\n./gh-wizard.sh --debug --performance --verbose\nset +x\n\n# Check log file for detailed execution trace\ncat logs/gh-issue-manager.log\n\n# View debug configuration dump\n./gh-wizard.sh --debug  # Shows configuration at startup\n```\n\n### Advanced Debugging Features\n\n```bash\n# Performance monitoring with thresholds\n./gh-wizard.sh --performance\n# Warns about operations taking \u003e2s (API) or \u003e5s (general)\n\n# Verbose console output\n./gh-wizard.sh --verbose\n# Shows detailed progress information\n\n# Custom log configuration\n./gh-wizard.sh --log-level DEBUG --log-file ./troubleshooting.log\n\n# Debug configuration dump\nDEBUG_MODE=true ./gh-wizard.sh\n# Shows all configuration variables at startup\n```\n\n## Contributing\n\n1. **Run tests before submitting PRs:**\n\n   ```bash\n   ./tests/run-all-tests.sh\n   ```\n\n2. **Follow the existing code style:**\n\n   - Use shellcheck for validation\n   - Add tests for new functionality\n   - Update documentation\n\n3. **Test coverage goals:**\n   - Maintain \u003e80% function coverage\n   - Add both unit and integration tests\n   - Include error scenario testing\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd-oit%2Fgh-sub-issues","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fd-oit%2Fgh-sub-issues","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd-oit%2Fgh-sub-issues/lists"}