{"id":31009397,"url":"https://github.com/bbenz/github-project-builder","last_synced_at":"2026-05-18T09:09:06.092Z","repository":{"id":313851600,"uuid":"1045173215","full_name":"bbenz/github-project-builder","owner":"bbenz","description":"Useful for teams that have been tracking issues in .csv compatible formats like a spreadsheet and now want to move to GitHub Issues. Automatically create a GitHub repository, project, and import sample issues with custom fields from a CSV file.","archived":false,"fork":false,"pushed_at":"2025-09-09T04:19:01.000Z","size":23,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-09T06:48:23.554Z","etag":null,"topics":["github","issues","issues-tracker","projects","repository"],"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/bbenz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-26T19:00:51.000Z","updated_at":"2025-09-09T04:20:30.000Z","dependencies_parsed_at":"2025-09-09T06:48:26.180Z","dependency_job_id":"47599595-b891-4ee2-bd13-60c8080f8571","html_url":"https://github.com/bbenz/github-project-builder","commit_stats":null,"previous_names":["bbenz/github-project-builder"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bbenz/github-project-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbenz%2Fgithub-project-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbenz%2Fgithub-project-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbenz%2Fgithub-project-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbenz%2Fgithub-project-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbenz","download_url":"https://codeload.github.com/bbenz/github-project-builder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbenz%2Fgithub-project-builder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274919792,"owners_count":25373953,"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-09-13T02:00:10.085Z","response_time":70,"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":["github","issues","issues-tracker","projects","repository"],"created_at":"2025-09-13T04:35:26.018Z","updated_at":"2026-05-18T09:09:01.058Z","avatar_url":"https://github.com/bbenz.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub Project Builder\n\nUseful for teams that have been tracking issues in .csv compatible formats like a spreadsheet and now want to move to GitHub Issues. \nAutomatically creates a GitHub repository, project, and imports sample issues with custom fields from a CSV file, in a comprehensive Bash script with embedded Python.\n\n## Features\n\n- **Repository Management**\n  - Creates new GitHub repositories or uses existing ones\n  - Supports both personal and organization repositories\n  - Automatic conflict detection and resolution options\n\n- **Project Management**\n  - Creates GitHub Projects (v2) with custom fields\n  - Detects and handles existing projects\n  - Supports multiple field types (Single Select, Number, Date, Text)\n  - Automatic field type detection and mapping\n\n- **CSV Import**\n  - Bulk import issues from CSV files\n  - Maps CSV columns to GitHub Project custom fields\n  - Preserves field relationships and data types\n  - Handles special characters and formatting\n\n- **Advanced Field Handling**\n  - Automatic detection of field types even when API returns generic types\n  - Proper handling of NUMBER and DATE fields with correct CLI flags\n  - Single Select fields with predefined options\n  - Field name conflict resolution (e.g., Status → WorkflowState)\n\n## Prerequisites\n\n1. **GitHub CLI (gh)**: Install from https://cli.github.com/\n2. **Python 3**: Required for CSV processing and API interactions\n3. **GitHub Authentication**: Run `gh auth login` before using the script\n\n## Installation\n\n1. Clone this repository:\n```bash\ngit clone https://github.com/yourusername/github-project-builder.git\ncd github-project-builder\n```\n\n2. Make the script executable:\n```bash\nchmod +x create-github-project-v4.sh\n```\n\n## Configuration\n\nEdit the configuration variables at the top of the script:\n\n```bash\nREPO_NAME=\"test-project-demo\"           # Repository name\nPROJECT_NAME=\"Project Management Board\"  # Project name\nCSV_FILE=\"test-issues.csv\"              # Path to CSV file\nPROJECT_SCOPE=\"user\"                    # \"user\" or \"org\"\nORG_NAME=\"\"                             # Required if PROJECT_SCOPE=\"org\"\n```\n\n## CSV Format\n\nYour CSV file should have the following structure:\n\n```csv\nTitle,Description,Priority,Status,EstimatedHours,DueDate,Team\n\"API endpoint refactoring\",\"Refactor REST API endpoints for better performance\",\"High\",\"Todo\",16,2025-09-01,\"Backend\"\n\"Create user dashboard\",\"Design and implement user dashboard\",\"Medium\",\"In Progress\",24,2025-09-10,\"Frontend\"\n```\n\n### Supported Field Types\n\n- **Title**: Issue title (required)\n- **Description**: Issue description (required)\n- **Priority**: Single select (High, Medium, Low)\n- **Status**: Single select (Todo, In Progress, Done, Blocked) - mapped to WorkflowState\n- **EstimatedHours**: Number field\n- **DueDate**: Date field (YYYY-MM-DD format)\n- **Team**: Single select (Frontend, Backend, API, Database, etc.)\n\n## Usage\n\n### Basic Usage (Personal Repository)\n\n```bash\n./create-github-project-v4.sh\n```\n\n### Organization Repository\n\n```bash\n# Edit the script to set:\nPROJECT_SCOPE=\"org\"\nORG_NAME=\"your-org-name\"\n\n./create-github-project-v4.sh\n```\n\n## Key Features Explained\n\n### 1. Intelligent Conflict Resolution\n\nThe script detects existing repositories and projects, offering options to:\n- Use existing resources\n- Create new ones with different names\n- Cancel the operation\n\n### 2. Field Type Detection\n\nThe script includes advanced logic to detect field types even when GitHub's API returns generic types:\n\n```python\n# Known field type mappings for fallback\nknown_types = {\n    'EstimatedHours': 'NUMBER',\n    'DueDate': 'DATE',\n    'Priority': 'SINGLE_SELECT',\n    'WorkflowState': 'SINGLE_SELECT',\n    'Team': 'SINGLE_SELECT'\n}\n```\n\n### 3. Proper Field Updates\n\nDifferent field types are handled with appropriate GitHub CLI flags:\n- `--number` for NUMBER fields\n- `--date` for DATE fields\n- `--single-select-option-id` for SINGLE_SELECT fields\n- `--text` for TEXT fields\n\n### 4. Reserved Field Name Handling\n\nThe script automatically handles GitHub's reserved field names:\n- Renames \"Status\" to \"WorkflowState\" to avoid conflicts\n- Skips creation of built-in fields like Title and Description\n\n### 5. Debug Mode\n\nThe script includes debug output for the first 2 issues to help troubleshoot field updates:\n\n```python\ndebug_mode = (i \u003c= 2)  # Debug first 2 issues\n```\n\n## Advanced Techniques\n\n### GraphQL API Integration (Optional)\n\nThe script can be extended with GraphQL mutations for more reliable field updates:\n\n```python\ndef update_field_via_graphql(project_id, item_id, field_id, value, field_type):\n    \"\"\"Update a field using GraphQL API directly.\"\"\"\n    # GraphQL mutation for NUMBER fields\n    mutation = f'''\n    mutation {{\n      updateProjectV2ItemFieldValue(input: {{\n        projectId: \"{project_id}\"\n        itemId: \"{item_id}\"\n        fieldId: \"{field_id}\"\n        value: {{ number: {value} }}\n      }}) {{\n        projectV2Item {{ id }}\n      }}\n    }}\n    '''\n```\n\n### Rate Limiting\n\nBuilt-in delays prevent hitting GitHub's rate limits:\n```python\ntime.sleep(1)  # Rate limiting between operations\n```\n\n### Error Handling\n\nComprehensive error handling with colored output:\n- 🔴 Red: Critical errors\n- 🟡 Yellow: Warnings and prompts\n- 🟢 Green: Success messages\n- 🔵 Blue: Information\n- 🟣 Magenta: Debug information\n\n## Troubleshooting\n\n### NUMBER and DATE Fields Not Updating\n\nIf NUMBER or DATE fields aren't updating:\n1. Check the debug output to verify field type detection\n2. Ensure dates are in YYYY-MM-DD format\n3. Verify numbers are valid (integers or floats)\n\n### Field Not Found Errors\n\nThis usually means:\n1. The field name in CSV doesn't match the project field\n2. The field hasn't been created yet\n3. There's a conflict with reserved field names\n\n### Authentication Issues\n\n```bash\n# Check authentication status\ngh auth status\n\n# Re-authenticate if needed\ngh auth login\n```\n\n## Script Versions\n\n- **v1**: Basic repository and project creation\n- **v2**: Added CSV import functionality\n- **v3**: Enhanced conflict resolution and field mapping\n- **v4**: Advanced field type detection and proper update handling\n\n## Contributing\n\nContributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.\n\n## License\n\nMIT License - feel free to use and modify for your needs.\n\n## Acknowledgments\n\nThis script was developed through iterative improvements to handle the complexities of GitHub's Project V2 API and provide a reliable way to bulk import issues with custom fields.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbenz%2Fgithub-project-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbenz%2Fgithub-project-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbenz%2Fgithub-project-builder/lists"}