🚀 Bitbucket to GitHub Migration Tool

A powerful command-line tool built with TypeScript and Bun for seamlessly migrating repositories from Bitbucket to GitHub. This tool supports both sequential and parallel migration modes with real-time progress tracking and comprehensive logging.

✨ Features

• Automated Repository Migration: Clone repositories from Bitbucket and push them to GitHub
• Parallel Processing: Migrate multiple repositories simultaneously for faster execution
• Smart Duplicate Detection: Automatically detects existing repositories and synchronization status
• Real-time Progress Tracking: Live status updates with detailed logging for each repository
• SSH Connectivity Verification: Pre-flight checks for SSH access to both platforms
• Automatic Repository Naming: Converts underscores to hyphens for GitHub compatibility
• Error Handling: Comprehensive error handling with detailed error messages
• Mirror Cloning: Preserves complete git history including all branches and tags
• Clean Temporary Files: Automatic cleanup of temporary directories after migration

📋 Prerequisites

Before using this tool, ensure you have the following:

Required Software

• Bun - JavaScript runtime and package manager
• Git - Version control system
• SSH Keys - Configured for both Bitbucket and GitHub

Environment Variables

Create a .env file or set the following environment variables:

export BITBUCKET_ORG="your-bitbucket-organization"
export GITHUB_ORG="your-github-organization"

🛠️ Installation

1. Install dependencies:

   bun install

2. Set up environment variables:

   cp .env.example .env
   # Edit .env with your organization names

🚀 Usage

Basic Migration

Migrate one or more repositories (comma-separated):

bun migrate repo1,repo2,repo3

Parallel Migration

For faster processing of multiple repositories:

bun migrate repo1,repo2,repo3 -p

Migration Examples

# Migrate a single repository
bun migrate my-awesome-project

# Migrate multiple repositories sequentially
bun migrate project-1,project-2,project-3

# Migrate multiple repositories in parallel
bun migrate project-1,project-2,project-3 --parallel

📖 Command Line Options

Option	Short	Description
--parallel	-p	Process repositories in parallel using Promise.all
--version	-V	Display version information
--help	-h	Show help information

🔄 Migration Process

The tool follows this migration workflow:

1. SSH Connectivity Check: Verifies SSH access to both Bitbucket and GitHub
2. Repository Existence Check: Checks if the repository already exists on GitHub
3. Mirror Clone: Clones the repository from Bitbucket with complete history
4. Remote Origin Update: Updates the remote origin to point to GitHub
5. Synchronization Check: Verifies if the repository is already up-to-date
6. Push to GitHub: Pushes all branches and tags to the GitHub repository
7. Cleanup: Removes temporary files and directories

📊 Status Indicators

During migration, you'll see real-time status updates:

Icon	Status	Description
⏳	Pending	Repository is queued for migration
📥	Cloning	Cloning from Bitbucket
🔗	Updating Origin	Updating remote origin to GitHub
🔍	Checking	Checking synchronization status
🚀	Pushing	Pushing to GitHub
✅	Success	Migration completed successfully
❌	Error	Migration failed
📦	Existing	Repository already exists and is synchronized

📁 Project Structure

bitbucket-github-migration-tool/
├── src/
│   ├── index.ts           # CLI entry point and command setup
│   ├── migrator.ts        # Main migration logic and orchestration
│   ├── log-manager.ts     # Real-time progress logging and status updates
│   ├── types.ts           # TypeScript interfaces and type definitions
│   └── enums.ts           # Status enums and constants
├── package.json           # Project dependencies and scripts
├── tsconfig.json          # TypeScript configuration
├── biome.json            # Code formatting and linting configuration
└── README.md             # Project documentation

🔧 Development

Prerequisites for Development

• Bun runtime
• TypeScript knowledge
• Git and SSH understanding

Available Scripts

# Run migration
bun migrate

# Lint and format code
bun run lint

# Run directly with Bun
bun run src/index.ts

Code Style

This project uses Biome for linting and formatting:

# Check and fix code style
bun run lint

⚠️ Important Notes

• Repository Naming: Repositories with underscores in Bitbucket will have them converted to hyphens in GitHub (e.g., my_repo → my-repo)
• Existing Repositories: The tool will skip repositories that already exist and are synchronized on GitHub
• SSH Requirements: Both Bitbucket and GitHub must be accessible via SSH
• Permissions: Ensure you have appropriate permissions to clone from Bitbucket and push to GitHub
• Large Repositories: Migration time depends on repository size and network speed

🐛 Troubleshooting

Common Issues

1. SSH Connection Failed:

   • Verify SSH keys are properly configured
   • Test connections with ssh -T [email protected] and ssh -T [email protected]

2. Environment Variables Missing:

   • Ensure BITBUCKET_ORG and GITHUB_ORG are set
   • Check that organization names are correct

3. Permission Denied:

   • Verify you have access to the Bitbucket repositories
   • Ensure you have push permissions to the GitHub organization

4. Repository Not Found:

   • Check repository names for typos
   • Verify the repository exists in the Bitbucket organization

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

Made with ❤️ using Bun and TypeScript