What Gets Migrated
Repository-focused migration preserving complete Git history, branches, tags, and pull requests.
Git Repositories
Branches & Tags
Pull Requests
Branch Protection Rules
Users & Permissions
Webhooks
Why This is the Simplest Migration: Repository migration is Git-native operation (no data transformation). Bitbucket and GitHub both use Git, so commit history, branches, and tags migrate perfectly via git clone --mirror + git push --mirror. Only pull requests, branch policies, and webhooks require OpsMigrator for conversion.
1. Prerequisites
Bitbucket Requirements
- Access Level: Admin access to repositories (Bitbucket Cloud or Server/DC)
- Authentication: App Password (Cloud) or Personal Access Token (Server/DC)
- API Access: Bitbucket REST API 2.0
- Permissions: Repository admin, PR read access
GitHub Requirements
- Organization: GitHub organization or personal account
- Authentication: Personal Access Token (classic) with full repo scope
- Permissions: Create repositories, manage settings, admin access
- API Access: GitHub REST API v3
Technical Requirements
- Minimum 4 GB RAM, 20 GB disk space (for repository clones)
- Git 2.30+ installed
- Network connectivity to Bitbucket and GitHub
- OpsMigrator CLI version 2.4+
2. Connector Setup
Step 1: Configure Bitbucket Connector
Generating Bitbucket App Password (Bitbucket Cloud):
- Navigate to Bitbucket.org → Personal settings → App passwords
- Click Create app password
- Label: "GitHub Migration"
- Configure permissions:
- Repositories: Read, Write, Admin
- Pull requests: Read
- Webhooks: Read and write
- Copy app password immediately (displayed once)
Bitbucket Connector Configuration:
{
"connectorType": "Bitbucket",
"baseUrl": "https://api.bitbucket.org/2.0",
"authentication": {
"authMethod": "AppPassword",
"username": "your-bitbucket-username",
"appPassword": "YOUR_APP_PASSWORD"
},
"bitbucketConfiguration": {
"workspace": "your-workspace",
"repositories": ["repo1", "repo2", "repo3"],
"includeAllRepos": false,
"type": "cloud"
},
"dataOptions": {
"includePullRequests": true,
"includeOpenPRsOnly": false,
"includeBranchPermissions": true,
"includeWebhooks": true,
"includeDefaultReviewers": true
}
}
Bitbucket Server/DC: If using Bitbucket Server or Data Center (on-premise), change baseUrl to https://bitbucket.company.com/rest/api/1.0 and use Personal Access Token instead of App Password. Set "type": "server" in configuration.
Step 2: Configure GitHub Connector
Generating GitHub Personal Access Token:
- Navigate to GitHub.com → Settings → Developer settings → Personal access tokens → Tokens (classic)
- Click Generate new token (classic)
- Configure scopes:
- repo (full control of private repositories)
- delete_repo (optional, for cleanup)
- admin:repo_hook (manage webhooks)
- admin:org (manage organization, if applicable)
- Set expiration: 90+ days
- Copy token immediately
GitHub Connector Configuration:
{
"connectorType": "GitHub",
"baseUrl": "https://api.github.com",
"authentication": {
"authMethod": "PersonalAccessToken",
"token": "ghp_YOUR_PERSONAL_ACCESS_TOKEN"
},
"githubConfiguration": {
"owner": "your-github-organization",
"createRepositories": true,
"visibility": "private",
"enableIssues": false,
"enableWiki": false,
"enableProjects": false
},
"migrationOptions": {
"preserveCommitHistory": true,
"preserveBranches": true,
"preserveTags": true,
"convertPullRequests": true,
"migrateBranchProtection": true,
"migrateWebhooks": true
}
}
Step 3: Validate Connections
# Validate both connectors
opsmigrator connector validate --source bitbucket-connector.json
opsmigrator connector validate --target github-connector.json
# Expected output:
✓ Bitbucket connection successful
- Workspace: your-workspace
- Repositories: 12 accessible
- Pull Requests: 247 (87 open, 160 closed)
- Branches: 94 total
- Webhooks: 8
✓ GitHub connection successful
- Organization: your-github-organization
- Create repository permission: Granted
- Rate Limit: 4,997/5,000 remaining
- User mapping: 92% matched (8% require provisioning)
3. Migration Process (4 Phases)
1
Discovery & Analysis
Duration: 2-4 hours
- Connect to Bitbucket and scan repositories
- AI analysis: Repository size, commit count, branch count
- Pull request analysis (open/closed)
- User identity mapping (Bitbucket → GitHub)
- Output: Migration plan with repo priorities
2
Configuration
Duration: 1 day
- Review repository list and migration order
- Configure GitHub organization settings
- Resolve unmapped users (provision GitHub accounts)
- Define branch protection rules
- Workshops: 1 session (1 hour)
3
Repository Migration
Duration: 1-2 days
- OpsMigrator clones repos from Bitbucket (--mirror)
- Push to GitHub (--mirror, preserves all refs)
- Convert pull requests (metadata migration)
- Migrate branch protection rules
- Recreate webhooks
- Throughput: 10-20 repos/day
4
Validation & Cutover
Duration: 1 day
- Comprehensive validation (commit count, branch count, tag count)
- User training on GitHub workflows
- Update CI/CD pipelines to GitHub repos
- Bitbucket read-only mode (optional)
- Support: 1 week hypercare
Git-Native Migration: OpsMigrator uses Git's native mirroring (git clone --mirror) to preserve 100% of repository data: commits, branches, tags, commit messages, author history, timestamps. This is identical to manual Git migration but automated across all repositories with validation and error handling.
Success Story
Enterprise SaaS Company - 3-Day Migration
- Scale: 67 repositories, 147,000 commits, 340 branches, 94 tags, 247 pull requests
- Challenge: 8 years of Git history, multiple long-lived branches, 160 closed PRs to preserve
- Result: 100% commit history preserved, 100% branch/tag preservation, 98.8% PR conversion success
- Timeline: 3 days total (6 hours repository migration, 1 day PR conversion, 1 day validation)
- Outcome: Seamless cutover, GitHub Actions deployed same day, Bitbucket decommissioned 2 weeks later, $18K annual savings
4. Pull Request Conversion
Pull Request Metadata Migration
Pull requests are NOT part of Git history (they're server-side metadata). OpsMigrator recreates them in GitHub:
| Bitbucket Field |
GitHub Field |
Transformation Notes |
| Title |
Title |
Direct mapping |
| Description |
Body |
Markdown preserved; Bitbucket mentions converted |
| State (OPEN/MERGED/DECLINED) |
State (open/closed) |
MERGED→closed (merged), DECLINED→closed, OPEN→open |
| Author |
Created by |
User identity mapping: Bitbucket username → GitHub account |
| Reviewers |
Requested reviewers |
Reviewers added to GitHub PR (for open PRs) |
| Source Branch |
Head branch |
Direct mapping (branch must exist in GitHub repo) |
| Destination Branch |
Base branch |
Direct mapping (typically main/master) |
| Comments |
Comments |
All comments preserved with original author and timestamp |
| Merge Commit SHA |
Merge commit SHA |
Links GitHub PR to actual merge commit in Git history |
Closed Pull Request Limitation
GitHub API Constraint: Closed/merged PRs cannot be created via API (GitHub only allows creating open PRs). OpsMigrator creates Issues labeled "Migrated PR" for closed PRs, preserving metadata (title, description, comments, merge commit link). This is GitHub platform limitation, not OpsMigrator limitation. Open PRs recreated perfectly as GitHub PRs.
Branch Protection Rules Migration
- Bitbucket Branch Permissions → GitHub Branch Protection: OpsMigrator converts Bitbucket branch permissions to equivalent GitHub branch protection rules
- Minimum Approvals: Bitbucket's "Minimum approvals: 2" → GitHub's "Required approving reviews: 2"
- Prevent Force Push: Direct mapping
- Require Builds to Pass: Maps to GitHub's "Require status checks to pass"
- Default Reviewers: Configured as CODEOWNERS file in GitHub (equivalent functionality)
Webhook Migration
- Bitbucket Webhooks → GitHub Webhooks: OpsMigrator recreates webhooks in GitHub with equivalent event triggers
- Event Mapping: repo:push → push, pullrequest:created → pull_request (opened), repo:commit_status_updated → status
- Payload Format: Different between Bitbucket and GitHub; receiving systems may need updates
- Webhook URLs: Preserved (external integrations like Slack, Jenkins continue working if they support GitHub format)
5. Red Flags & Mitigation
Detection: 3 repositories exceed 5 GB each (Git history includes large binaries)
Impact: Migration time increases significantly; GitHub has 100 GB per repo soft limit.
Mitigation:
- Use Git LFS (Large File Storage) for binaries (requires rewriting Git history)
- Archive historical large files to external storage (reduces repo size 40-70%)
- GitHub supports up to 100 GB per repo (contact GitHub support if exceeding)
- For repos >20 GB: Budget 4-8 hours per repo for migration (network bandwidth dependent)
Detection: 160 closed/merged pull requests in Bitbucket
Impact: Cannot be recreated as GitHub PRs (API limitation); preserved as Issues instead.
Mitigation:
- OpsMigrator creates GitHub Issues labeled "Migrated PR" for closed PRs
- Issue contains full PR metadata: title, description, comments, author, merge commit link
- Users can click merge commit link to view actual code changes in Git history
- 98% of teams find this acceptable (closed PRs are historical reference, not operational)
Detection: 8 Bitbucket users have no matching GitHub account
Impact: PRs, comments, and reviews cannot be assigned to correct GitHub users.
Mitigation:
- Export user mapping report from OpsMigrator
- Provision GitHub accounts for active users (coordinate with IT)
- Map retired users to generic "Historical User" account
- Original Bitbucket username preserved in comments/descriptions
Detection: 34 repositories have bitbucket-pipelines.yml files
Impact: Bitbucket Pipelines YAML incompatible with GitHub Actions; manual conversion required.
Mitigation:
- OpsMigrator provides pipeline conversion assistant (40-60% automated)
- Budget 1-3 hours per pipeline for manual conversion and testing
- Alternatively: Use third-party CI/CD (Jenkins, CircleCI) that supports both Bitbucket and GitHub
- GitHub Actions templates available for common patterns (Node.js, Python, Docker)
6. Best Practices
Before Migration
- User Provisioning: Ensure all active Bitbucket users have GitHub accounts 1-2 weeks before migration
- Repository Cleanup: Archive unused repositories (reduces migration scope by 20-40%)
- Git LFS Evaluation: For repos with large binaries, plan Git LFS migration 2-4 weeks in advance
- CI/CD Inventory: Document all Bitbucket Pipelines and external integrations (requires post-migration updates)
- Communication: Notify team 1 week before migration; plan training session on GitHub workflows
During Migration
- Bitbucket Remains Active: No need to freeze Bitbucket; migration clones data without locking
- Pilot First: Migrate 1-2 repositories as proof of concept (validates process)
- Sequential Migration: Migrate repos one at a time (easier to troubleshoot)
- Bandwidth Monitoring: Large repos (>5 GB) may take 2-4 hours each; schedule during off-hours
- Real-Time Validation: OpsMigrator validates commit count, branch count, tag count after each repo
After Migration
- Parallel Operation: Run Bitbucket (read-only) and GitHub in parallel for 1-2 weeks
- CI/CD Updates: Update all pipelines, build servers, deployment scripts to point to GitHub repos
- User Training: Conduct GitHub training (2-hour workshop on PRs, Actions, Projects)
- Webhook Testing: Test all migrated webhooks (Slack, Jira, Jenkins) to ensure GitHub format compatibility
- Bitbucket Decommissioning: Archive Bitbucket workspace 2-4 weeks after successful cutover (keep read-only for 3-6 months)
7. Frequently Asked Questions
Is 100% of Git history preserved?
Yes. OpsMigrator uses Git's native mirroring (git clone --mirror + git push --mirror) which preserves 100% of repository data: all commits, branches, tags, commit messages, author history, timestamps, merge commits. This is identical to manual Git migration. GitHub repo will be exact copy of Bitbucket repo from Git perspective.
What happens to Bitbucket Pipelines?
Bitbucket Pipelines YAML files (bitbucket-pipelines.yml) are migrated to GitHub repository but NOT functional. Must manually convert to GitHub Actions YAML (.github/workflows/). OpsMigrator provides conversion assistant (40-60% automated) but human review required. Budget 1-3 hours per pipeline. Common alternative: Use third-party CI/CD (Jenkins, CircleCI) that supports both platforms.
Can I keep using Bitbucket after migration?
Yes. Recommended approach: Put Bitbucket in read-only mode (disable push permissions) after migration complete. Keep accessible for 2-4 weeks during parallel operation. This allows rollback if issues discovered. After successful cutover, archive Bitbucket workspace (keep for 3-6 months for compliance/reference). Bitbucket does NOT need to be deleted immediately.
How long does Bitbucket need to be offline?
Bitbucket does NOT need to be offline. Migration is clone operation (read-only, no data locked). Teams continue committing to Bitbucket during migration if needed. However, recommend freezing Bitbucket (read-only) 24 hours before migration to prevent data drift. After migration, incremental sync available to capture any last-minute commits.
What about closed pull requests?
Closed/merged PRs cannot be recreated as GitHub PRs (GitHub API limitation). OpsMigrator creates GitHub Issues labeled "Migrated PR" containing full PR metadata (title, description, comments, merge commit link). Users can click merge commit link to view code changes in Git history. Open PRs recreated perfectly as GitHub PRs. 98% of teams find this acceptable (closed PRs are historical reference).
What's the typical cost for Bitbucket → GitHub migration?
- Small (10-30 repos): $5K-$10K (2-3 days, includes OpsMigrator license, consulting)
- Medium (30-100 repos): $10K-$20K (3-5 days, includes training, pipeline guidance)
- Large (100-300+ repos): $20K-$40K (5-10 days, includes pipeline conversion, Git LFS migration)
Costs include: OpsMigrator license, consultant fees, GitHub licensing (if new), user training. Pipeline conversion (if needed): add $3K-$15K depending on pipeline complexity. This is lowest-cost migration scenario (repository migration simpler than issue tracking transformation).
Ready to Migrate to GitHub?
Schedule a demo to see how OpsMigrator simplifies Bitbucket to GitHub repository migration.