GitPorter

Fetch your GitHub issue workflow faster with GitPorter: plan, import, and bulk update at pack speed.

Install

Run with npx (no global install):

npx gitporter help

Or install globally:

npm install -g gitporter
gitporter help

Standalone binaries

GitHub Releases also publish standalone binaries for Linux, macOS, and Windows.

1. Download the asset matching your platform from the latest bin/v* release.
2. Verify the checksum against SHA256SUMS.txt.
3. Extract and run:

./gitporter help

Windows PowerShell:

.\gitporter.exe help

Quick start

1. Set environment variables:

• Required for GitHub API operations (import apply, cleanup, export, update): GITHUB_TOKEN (or pass --token per command)
• Optional defaults for repository targeting: GITHUB_OWNER, GITHUB_REPO (or pass --owner / --repo per command)

2. Generate a template CSV:

gitporter template --out ./gitporter.import.template.csv

3. Validate your CSV first:

gitporter validate --csv ./gitporter.import.template.csv

4. Preview changes without writing:

gitporter import --csv ./gitporter.import.template.csv --dry-run

5. Run import:

gitporter import --csv ./gitporter.import.template.csv

Core commands

• gitporter template: Generate an import-ready CSV template.
• gitporter import: Import issues from CSV.
• gitporter cleanup: Close issues from CSV selection or close all.
• gitporter validate: Validate CSV schema and row data.
• gitporter plan: Preview creates, closes, and updates.
• gitporter export: Export repository issues to normalized CSV.
• gitporter update: Compare/apply updates from normalized CSV.
• gitporter help: Show usage and examples.

Basic examples

# Import from normalized CSV
gitporter import --csv ./issues.csv --owner demo-org --repo demo-repo

# Preview cleanup targets
gitporter cleanup --owner demo-org --repo demo-repo --csv ./issues.csv --dry-run

# Plan import actions with JSON output
gitporter plan --mode import --csv ./issues.csv --owner demo-org --repo demo-repo --json

Detailed docs and FAQ

Detailed command options, CSV schema notes, and frequently asked questions live in the wiki:

• Wiki Home
• CLI Command Reference
• Import command
• Cleanup command
• Validate command
• Plan command
• Export command
• Update command
• CSV Format and Examples
• FAQ

Development and contributing

Development setup, local npm run workflows, testing, and PR guidance live in CONTRIBUTING.md.