GitHub Project Import

A Node package that imports issues from a YAML file into a GitHub repository using the GitHub API. Perfect for creating GitHub projects from templates, converting project blueprints into actionable issues, and updating existing projects with new tasks.

⚠️ Hybrid Approach
This tool uses REST API for issue management and GraphQL for Projects v2 functionality, providing the best of both worlds.

⚠️ EXPERIMENTAL
This project was created as a testing experiment using Claude Sonnet 4.5. It is not very well tested yet, so please use cautiously, especially when trying to update existing projects. I recommend trying it first in personal projects or accounts.

📝 TODO

• Issue relation - It seems not yet available by GH api or cli.
• Interactive mode - You can decide step by step which issues to keep or overwrite

Accepting improvement ideas

🚀 Quick Start

Get GitHub Personal Access Token

1. Go to GitHub Settings > Developer settings > Personal access tokens
2. Click "Generate new token (classic)"
3. Select scopes: repo, project, write:org (if using organization projects)
4. Copy the token (you won't see it again!)

Usage

cp env.example .env  # if you want to use .env
cp project.example.yml project.yml # copy the example SaaS blueprint project and customize it for your needs

# run with env vars
GITHUB_USERNAME=myusername \
GITHUB_YAML_FILE=project.yml \
GITHUB_PROJECT_NAME="Acme Project" \
GITHUB_TOKEN=my-gh-token \
GITHUB_REPO="my-repo" \
  npx ghpi create

# run with cli args
npx ghpi create \
  --owner myusername \
  --repo my-repo \
  --token my-gh-token
  --yaml project.yml \
  --projectName "Acme Project"

📋 Requirements

System Requirements

• Node.js: Version 22.0.0 or higher
• npm: Version 8.0.0 or higher (or pnpm/yarn)
• Git: For version control and repository access

GitHub Requirements

Personal Access Token

You need a GitHub Personal Access Token with the following scopes:

| Scope | Required | Description | | ----------- | ------------------ | ------------------------------------------------------- | | repo | ✅ Required | Full access to repositories (create/read/update issues) | | project | ✅ Required | Access to GitHub Projects v2 (create/manage projects) | | write:org | ⚠️ Conditional | Required only if using organization projects |

Repository Access

• Owner permissions: You must have write access to the target repository
• Organization projects: Admin access required for organization-owned projects
• Personal projects: Owner access required for personal repositories

Project Permissions

• Create projects: Requires project scope and repository write access
• Update projects: Requires project scope and project admin access
• Add issues to projects: Requires both repo and project scopes

File Requirements

YAML File

• Format: Valid YAML syntax
• Structure: Must follow the YAML format specification
• Encoding: UTF-8 encoding recommended
• Size: No hard limit, but very large files may hit API rate limits

Environment Configuration

• .env file: Optional, but recommended for security
• Environment variables: Can be set in shell or CI/CD systems
• CLI arguments: Can override environment variables

Network Requirements

• Internet connection: Required for GitHub API access
• HTTPS: All GitHub API calls use HTTPS
• Rate limits: GitHub API has rate limits (5000 requests/hour for authenticated users)
• Firewall: Ensure outbound HTTPS connections to api.github.com are allowed

Development Requirements (for contributors)

• TypeScript: Version 5.9.3 or higher
• Jest: For running tests
• ESLint: For code linting
• Prettier: For code formatting
• GitHub CLI: Optional, for project linking

Troubleshooting Requirements

If you encounter issues, ensure you have:

1. Valid GitHub token with correct scopes
2. Repository write permissions
3. Project permissions (for project operations)
4. Valid YAML file with correct syntax
5. Network connectivity to GitHub API
6. Sufficient API rate limit remaining

Security Requirements

• Token security: Never commit tokens to version control
• Environment variables: Use .env files or secure environment variable storage
• Repository access: Only use tokens with minimal required permissions
• Audit logs: Monitor GitHub API usage in your account settings

The import YAML format

See example

Options

| Option | Environment Variable | CLI Argument | Default | Required | Description | | ----------------- | --------------------- | ---------------- | ------- | -------- | ----------------------------------------- | | GitHub Owner | GITHUB_OWNER | --owner | - | true | GitHub username or organization | | Repository | GITHUB_REPO | --repo | - | true | GitHub repository name | | YAML File | GITHUB_YAML_FILE | --yaml | - | true | Path to your YAML file | | GitHub Token | GITHUB_TOKEN | --token | - | true | GitHub personal access token | | Project Name | GITHUB_PROJECT_NAME | --projectName | - | true | Project name (required for creation mode) | | Project ID | GITHUB_PROJECT_ID | --projectId | - | true | Project ID (required for update mode) | | Dry Run | DRY_RUN | --dry-run | false | - | Test mode without making changes | | Debug | DEBUG | --debug | false | - | Enable detailed logging | | Upsert Issues | UPSERT_ISSUES | --upsertIssues | false | - | Update existing issues in update mode |

Dry run

Use dry run mode to verify that you have all the necessary permissions from GitHub before making actual changes.

# Test with dry run (recommended first)
npx ghpi dry-run

# Or using direct command
npx ghpi create --owner myusername --repo my-repo --yaml project.yml --token my-gh-token --projectName "Acme Project" --dry-run true

Finding Your Project ID:

1. Go to your GitHub Project
2. Look at the URL: https://github.com/orgs/your-org/projects/123
3. The Project ID is the number at the end of the URL (e.g., 123)
4. Or go to your repository's Projects tab to see project numbers

🛠️ NPM Scripts

For convenience, several npm scripts are available:

# Show help and all available options
npx ghpi help

# Quick creation mode (requires env vars for other values)
npx ghpi create

# Quick update mode (requires env vars for other values)
npx ghpi update

# Run in dry-run mode
npx ghpi dry-run

# Run with debug logging
npx ghpi debug

# Development and Testing
npm test              # Run tests
npm run test:watch    # Run tests in watch mode
npm run test:coverage # Run tests with coverage
npm run test:ci       # Run tests for CI

# TypeScript
npm run build         # Build TypeScript to JavaScript
npm run build:watch   # Build in watch mode
npm run type-check    # Type check without emitting files
npm run start:dev     # Run TypeScript directly with tsx
npm run dev           # Build and run (convenience script)

# Code Quality
npm run format        # Format code with Prettier
npm run format:check  # Check code formatting

# Git and Release
npm run commit        # Interactive commit with commitizen
npm run release       # Run semantic release

📊 Output Examples

Creation Mode Output

🚀 GitHub Project Import Script (GitHub API Version)
📁 YAML File: project.yml
🏢 Owner: myusername
📦 Repository: my-repo
🔄 Mode: CREATION
📋 Project Name: My SaaS Project

📊 Found 81 total items across 8 sections
🔄 Mode: CREATION

📋 Creating GitHub Project: My SaaS Project - 10/9/2025
✅ Project created: #123

📂 Importing section: Foundation / Setup (23 items)
  ➕ Creating new issue: "Project scaffolding and base folder structure"
  📝 Created issue #456: Project scaffolding and base folder structure
    🏷️ Priority: critical | Tags: foundation, ops

🎉 Import completed!
📊 Summary:
  🔄 Mode: CREATION
  ✅ Processed: 81 issues
  ❌ Errors: 0 failed
  📋 Project: #123
  🔗 View project: https://github.com/myusername/my-repo/projects/123

Update Mode Output

🚀 GitHub Project Import Script (GitHub API Version)
📁 YAML File: project.yml
🏢 Owner: myusername
📦 Repository: my-repo
🔄 Mode: UPDATE
📋 Project ID: 123

📊 Found 81 total items across 8 sections
🔄 Mode: UPDATE

📋 Using existing GitHub Project: 123
✅ Project found: 123

📂 Importing section: Foundation / Setup (23 items)
  🔄 Updating existing issue: "Project scaffolding and base folder structure"
  📝 Updated issue #456: Project scaffolding and base folder structure
    🏷️ Priority: critical | Tags: foundation, ops
  ➕ Creating new issue: "New feature implementation"
  📝 Created issue #789: New feature implementation
    🏷️ Priority: high | Tags: frontend, feature

🎉 Import completed!
📊 Summary:
  🔄 Mode: UPDATE
  ✅ Processed: 81 issues
  ➕ Created: 5 new issues
  🔄 Updated: 76 existing issues
  ❌ Errors: 0 failed
  📋 Project: 123

📋 YAML File Format

See YAML Format Guide for detailed YAML file structure and field descriptions.

🔧 Configuration

See Configuration Guide for detailed configuration options and environment variables.

📊 Usage Examples

See Usage Examples for practical examples and output samples.

🛡️ Safety Features

See Safety Features for dry run mode, validation, and best practices.

📈 Output Example

See Usage Examples for detailed output examples.

🐛 Troubleshooting

See Troubleshooting Guide for common issues and debugging steps.

🧪 Development & Testing

See Contributing Guide for detailed development setup and testing instructions.

📚 Documentation

For detailed documentation, see the /docs folder:

• Contributing - Development workflow and contribution guidelines
• Configuration - Environment variables and setup options
• Usage Examples - Practical examples and output samples
• YAML Format - YAML file structure and field descriptions
• Safety Features - Dry run mode, validation, and best practices
• Troubleshooting - Common issues and debugging steps
• Support - Getting help and reporting issues
• License - License information

🤝 Contributing

See Contributing Guide for development workflow and guidelines.

📄 License

See License for license information.

📁 Example Files

• env.example - Example environment configuration
• project.example.yml - Comprehensive SaaS project template with 81+ items
• project.yml - Your actual project file (copy from example)

The example files provide a complete SaaS foundation template with:

• 🏗️ Foundation & Setup (23 items)
• 🔧 Backend & API (11 items)
• 🔐 Authentication & Authorization (6 items)
• 💳 Billing & Monetization (7 items)
• 🎨 Frontend & App (16 items)
• ⚙️ Admin Panel (11 items)
• 🚀 CI/CD (4 items)
• 📚 Documentation (5 items)
• ⚖️ Legal & Compliance (9 items)

🆘 Support

See Support Guide for getting help and reporting issues.