Migrating from Bitbucket to GitHub 🔄

Decided to move from Bitbucket to GitHub? Here’s how to migrate your repositories the right way!

Why migrate?

Reasons to switch to GitHub:

✅ Large community (100M+ developers)
✅ Better for your portfolio
✅ GitHub Actions (powerful CI/CD)
✅ GitHub Pages (free hosting)
✅ More integrations
✅ More popular with employers

Bitbucket is still great for:
- Jira integration
- Corporate setup
- Pipelines (built-in CI/CD)

Method 1: Via GitHub Desktop (EASY!)

Step 1: Clone from Bitbucket

1. Open your Bitbucket repository
2. Copy the HTTPS URL
3. GitHub Desktop → File → Clone Repository
4. Switch to the URL tab → paste the Bitbucket URL
5. Click Clone

Step 2: Publish to GitHub

1. After cloning, click Publish repository
2. Choose a name and description
3. Select Public or Private
4. Click Publish Repository

✅ Done! Your code has been moved from Bitbucket to GitHub!

Method 2: Via the command line

Full migration with history

# 1. Clone from Bitbucket (bare clone)
git clone --bare https://bitbucket.org/username/repo.git

# 2. Enter the directory
cd repo.git

# 3. Create a repository on GitHub.com
# Go to github.com/new and create the repo

# 4. Mirror-push to GitHub
git push --mirror https://github.com/username/repo.git

# 5. Remove the temporary directory
cd ..
rm -rf repo.git

# 6. Clone from GitHub for day-to-day work
git clone https://github.com/username/repo.git

Command breakdown

--bare — clones only the Git data (no working files)

--mirror — copies EVERYTHING:
- All branches
- All tags
- The full history
- All refs

Method 3: GitHub Importer (AUTOMATIC!)

Via the GitHub web interface

1. Go to github.com/new/import
2. Paste the Bitbucket URL:
   https://bitbucket.org/username/repo
3. If the repo is private — enter your credentials
4. Choose a name for the new repository
5. Select Public/Private
6. Click Begin import

GitHub will automatically:
- Clone the code
- Migrate the full history
- Migrate all branches
- Create the new repository

Takes 5–15 minutes.

What gets migrated?

✅ Migrated

• Code (all files)
• Commit history
• Branches
• Tags
• Contributors (commit authors)

❌ NOT migrated

• Issues
• Pull Requests
• Wiki pages
• Build Pipelines
• Webhooks
• Branch permissions

These need to be migrated manually or via plugins (rarely necessary).

After migration

1. Update your README

Add a GitHub badge:

# My Project

![GitHub Stars](https://img.shields.io/github/stars/username/repo)
![GitHub Forks](https://img.shields.io/github/forks/username/repo)

2. Set up GitHub Actions

Create .github/workflows/ci.yml:

name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run tests
        run: npm test

3. Add CODEOWNERS

```.github/CODEOWNERS
* @username
/docs/ @docs-team

### 4. Configure Branch Protection

1. Settings → Branches
2. Add a rule for `main`
3. ✅ Require pull request reviews
4. ✅ Require status checks

### 5. Update links

Everywhere a Bitbucket link appeared:

- README.md
- Documentation
- CI/CD configs
- Webhooks
- Deployment scripts

Replace them with GitHub URLs.

## Team migration: moving together

### Notify your team

```markdown
## 🚀 We've moved to GitHub!

**Old repository (DO NOT USE):**
https://bitbucket.org/team/project

**New repository:**
https://github.com/team/project

**Action items:**
1. Delete your old clone
2. Clone from GitHub
3. Update the remote in existing clones

Update the remote in existing clones

If team members already have a local clone:

# Check the current remote
git remote -v

# Switch to GitHub
git remote set-url origin https://github.com/username/repo.git

# Verify the change
git remote -v

Migrating multiple repositories

If you need to move 10+ repositories:

Automation script

#!/bin/bash

# List of repositories
repos=(
  "repo1"
  "repo2"
  "repo3"
)

for repo in "${repos[@]}"; do
  echo "Migrating $repo..."

  # Clone from Bitbucket
  git clone --bare https://bitbucket.org/username/$repo.git

  # Push to GitHub
  cd $repo.git
  git push --mirror https://github.com/username/$repo.git

  # Cleanup
  cd ..
  rm -rf $repo.git

  echo "$repo migrated!"
done

Save as migrate.sh, make it executable, and run it:

chmod +x migrate.sh
./migrate.sh

Platform comparison

Common issues

“Authentication failed”

Solution:

For Bitbucket with 2FA you need an App Password:

1. Bitbucket → Personal settings → App passwords
2. Create an app password
3. Use it instead of your regular password

Large repository (> 1 GB)

Solution:

1. Use git filter-branch to remove large files from history
2. Or Git LFS for large files
3. Or BFG Repo-Cleaner

Different commit authors

Git preserves the original authors. If you need to rewrite them:

git filter-branch --env-filter '
export GIT_AUTHOR_EMAIL="new@email.com"
export GIT_COMMITTER_EMAIL="new@email.com"
'

Rolling back the migration

Changed your mind? You can reverse it the same way:

git clone --bare https://github.com/username/repo.git
cd repo.git
git push --mirror https://bitbucket.org/username/repo.git

Wrap-up

Migrating from Bitbucket to GitHub:

✅ Simple (3–5 minutes per repository)
✅ Preserves history
✅ Can be automated

Choose GitHub for:
- Open-source projects
- Portfolio
- Community

Stay on Bitbucket if:
- You rely heavily on Jira
- Your corporate setup is already configured
- Bitbucket Pipelines are working perfectly

Happy migrating! 🚀