migrating toBrowse playbooks
← All playbooks
Development migration

Bitbucket → GitHub

Move scoped Bitbucket repositories to GitHub, with pull-request metadata available only for eligible Server/Data Center 5.14+ migrations through GitHub Enterprise Importer; Cloud uses source-and-history-only migration.

Typical timelineEditorial estimate: 15–30 business daysEditorial estimate: 60–110 hours active work
Statusagent reviewed
Source profileBitbucket Cloud and Data Center paths reviewed 2026-07-27
Destination profileGitHub migration guidance reviewed 2026-07-27
Documentation date
Review window
Evidence5 sources
This route was independently agent reviewed.Its documented claims passed a two-agent source review. It is not a substitute for a representative migration test before production.
Before you migrate

Should you make this move?

Both platforms have a case. Compare what you gain with what you give up before scheduling the cutover.

Current platform

Bitbucket

Reasons to stay
  • Native Jira integration fits teams already standardized on Atlassian
  • Repository-centered workflows keep code, review, and automation close together
Reasons to leave
  • Its ecosystem and community surface are smaller than GitHub's
  • Advanced governance and automation can become configuration-heavy
New platform

GitHub

What gets better
  • The largest developer ecosystem combines collaboration, automation, and public discovery
  • Repository-centered workflows keep code, review, and automation close together
What gets worse
  • Enterprise planning and governance can require several overlapping GitHub products
  • Advanced governance and automation can become configuration-heavy
Best of the move

GitHub: The largest developer ecosystem combines collaboration, automation, and public discovery. This removes a major source-side concern: Its ecosystem and community surface are smaller than GitHub's.

Worst of the move

What you lose: Native Jira integration fits teams already standardized on Atlassian. What you inherit: Enterprise planning and governance can require several overlapping GitHub products.

Connected catalog

2 destinations are documented from Bitbucket. Compare nearby routes before committing.

Also from Bitbucket
Also moving to GitHub
Jump to a section
01At a glance

Know the shape of the move.

Transfer outcome14 features audited
Transfer outcome distributionClean transfer: 1, Partial transfer: 4, Manual rebuild: 4, Not transferred: 5.
Clean1
Partial4
Manual4
Lost5
Mapping route7 of 8 fields have a destination path

This timeline assumes

  • Editorial planning scale: up to 100 repositories with Git, LFS, Pipelines, and common integrations.
  • Bitbucket Cloud uses a source-and-history-only path; Bitbucket Server/Data Center 5.14 or later may use GitHub Enterprise Importer.
  • Production deploys freeze during final mirror and CI switch.
  • All repositories and wikis receive offline mirror backups.
  • Secrets are rotated rather than exported.
02What transfers

What survives the move.

“Partial” and “manual” are not footnotes. They are work that must be scheduled and verified.

ItemOutcomeImpactWhat happensMitigation
Scoped user branches, tags, and commitscleancriticalMirror clone and push preserve the approved user-ref history; provider-owned or synthetic refs are classified separately.Record the approved ref scope, compare those tips and commit graphs, and run fsck.
Git LFS objectsmanualcriticalGitHub Enterprise Importer does not migrate LFS objects; source-and-history moves also require a separate LFS transfer.Fetch and push LFS separately, then compare object inventories and checksums.
Pull requests and comments — Bitbucket CloudlosthighThe supported Bitbucket Cloud path carries Git source and history, not pull-request collaboration metadata.Archive required pull requests and link the archive from GitHub.
Pull requests and comments — Server/Data Center 5.14+partialhighGitHub Enterprise Importer migrates pull requests, comments, reviews, line comments, required reviewers, and attachments, subject to migration limits and logs.Pilot representative pull requests and reconcile the importer logs.
Issues and wikimanualhighThey require separate migration or archival paths.Export issues and mirror the wiki repository.
Contribution attribution and mannequinspartialhighEligible Server/Data Center metadata imports can create mannequins for source authors; reclaiming attribution does not grant live repository access.Map and reclaim mannequins separately from team membership and permission provisioning.
Live access, branch restrictions, and repository settingsmanualcriticalThe Server/Data Center importer does not migrate branch permissions, repository settings, or live access; imported repositories are private by default. Reclaimed mannequins restore attribution only.Provision teams and repository roles separately, then rebuild rulesets, settings, reviews, and CODEOWNERS before granting write access.
Git and archive limitspartialcriticalLimits include a 2 GiB single commit, 255-byte refs, 100 MiB final files, 400 MiB files during GEI, and a public-preview 40 GiB combined Git data plus metadata repository archive limit for Server/Data Center GEI.Scan and remediate limit violations before production migration.
Personal repositories — Server/Data CenterlosthighGitHub Enterprise Importer does not migrate Bitbucket personal repositories.Move approved personal repositories into a migratable project first or use a separate source-and-history path.
Commit comments — Server/Data CenterlostmediumGitHub Enterprise Importer does not migrate commit comments.Archive required commit-comment context and link it from the destination repository.
Bitbucket PipelinespartialcriticalGitHub Actions Importer can convert workflows, but manual validation remains.Audit, dry-run, review, and exercise every release path.
Secrets and deployment variableslostcriticalSecret values do not transfer safely.Rotate into protected GitHub environments and secrets.
Downloads, packages, and artifactsmanualhighBinary assets and registries have separate paths.Inventory, copy, checksum, and test consumers.
Webhooks, apps, keys, and integrationslostcriticalInstallation and credential state is platform-specific.Reauthorize or replace each integration.
03Field and feature mapping

Where each thing goes.

SourceDestinationMethodNotes
Workspace/projectOrganization/teammanualDesign namespace and access first.
RepositoryRepositoryautomaticConfirm visibility and default branch.
Approved user branches and tagsGitHub branches and tagsautomaticCompare the approved ref scope and classify provider-owned refs separately.
Bitbucket Server/Data Center contribution authorGitHub mannequin or reclaimed attributiontransformOnly eligible Server/Data Center GEI metadata imports create this path; Cloud source-only migration does not, and attribution remains separate from live permissions.
Branch restrictionRuleset/branch protectionmanualRebuild and negative-test.
bitbucket-pipelines.yml.github/workflows/*.ymltransformUse Actions Importer then review.
Deployment variableEnvironment secretmanualRotate values.
Webhook/appNo destinationunsupportedReinstall or replace.
04Before you begin

Make the move recoverable.

Backup procedure

Create the source-of-truth backup

Preserve repositories and every operational dependency.

  1. Inventory repos, refs, LFS, wikis, PRs, issues, policies, pipelines, runners, secrets, artifacts, and integrations.
  2. Mirror clone repos and wikis, fetch all LFS, and run fsck.
  3. Export collaboration counts and required metadata.
  4. Checksum assets and record secret names/consumers.
  5. Test one restore.

Proof to capture: A repository manifest reconciles refs, objects, metadata, policy, CI, assets, and integrations.

Transformation · GitHub Actions Importer

CI conversion

Create reviewed GitHub Actions workflows.

  1. Audit pipelines.
  2. Run dry-run conversion.
  3. Review permissions and test build, release, deploy, and rollback.

Proof to capture: Save the input, output, command or tool settings, warnings, and final item counts.

Transformation · Migration workbook

Policy and identity map

Recreate least privilege and merge controls.

  1. Map users and teams.
  2. Map restrictions to rulesets.
  3. Run forbidden-action tests.

Proof to capture: Save the input, output, command or tool settings, warnings, and final item counts.

05Handle with care

The things most likely to hurt.

These are operating limits. Treat every “Stop if” condition as a blocked migration, not a suggestion.

Cutover

Repositories diverge

criticalpossible likelihood

A Bitbucket ref advances after final mirror.

Consequence
Code and releases split.
Mitigation
Freeze writes and lock the source.

Stop if: Any uncaptured source ref advances.

CI

CI permissions broaden

criticalpossible likelihood

Untrusted workflows read protected secrets.

Consequence
Infrastructure compromise.
Mitigation
Minimize token permissions and protect environments.

Stop if: A pull request can access production credentials.

Access

Policy disappears

criticalpossible likelihood

Forbidden push or merge succeeds.

Consequence
Unreviewed code reaches production.
Mitigation
Run negative role tests.

Stop if: Any required control fails.

06Precise timeline

Do the work in this order.

Estimate forEditorial estimate for up to 100 repositories
Total elapsedEditorial estimate: 15–30 business days
Active workEditorial estimate: 60–110 hours
BufferAdd time for complex pipelines, large LFS, or enterprise metadata migration.
01
Days 1–4Inventory4 days
02
Days 5–7Mirrors3 days
03
Days 8–12Pilot5 days
04
Days 13–22Migration waves6–10 days
05
Days 23–30Final mirror and observation5–8 days
  1. Days 1–4 · inventory

    Inventory

    16–24 hours active4 days elapsedOwner review waiting
    • Inventory data and dependencies.
    • Design organizations, teams, policy, and waves.

    Depends on: Admins

    Stop / go checkpoint

    Back up?

    Go when: Every repo and production dependency has an owner.

    Stop when: Critical CI or secret consumer is unknown.

  2. Days 5–7 · backup

    Mirrors

    10–18 hours active3 days elapsedClone and LFS transfer waiting
    • Create mirrors and metadata archives.
    • Validate restore.

    Depends on: Scope

    Stop / go checkpoint

    Pilot?

    Go when: Refs, LFS, wiki, and assets reconcile.

    Stop when: Any critical object is missing.

  3. Days 8–12 · pilot

    Pilot

    15–24 hours active5 days elapsedCI runs waiting
    • Migrate representative repos.
    • Translate CI and policies.
    • Test release and rollback.

    Depends on: Backup

    Stop / go checkpoint

    Waves?

    Go when: All repo archetypes pass.

    Stop when: Data, policy, or CI fails.

  4. Days 13–22 · waves

    Migration waves

    15–32 hours active6–10 days elapsedImports and reviews waiting
    • Freeze writes before each Server/Data Center GEI production migration; use a separately controlled final mirror for Cloud repositories.
    • Reconcile scoped refs, pull requests, comments, reviews, attachments, mannequins, and logs; keep every Server/Data Center source frozen until final cutover completes.

    Depends on: Pilot

    Stop / go checkpoint

    Cut over?

    Go when: Every repo is complete or excepted.

    Stop when: Any critical variance remains.

  5. Days 23–30 · cutover

    Final mirror and observation

    4–12 hours active5–8 days elapsedNormal workflows waiting
    • Keep Server/Data Center repositories frozen through the control-plane switch; freeze Cloud and mirror its final approved refs.
    • Switch CI, remotes, webhooks, and deploys only after route-specific data and metadata reconciliation.
    • Observe releases before lifting any retained source access.

    Depends on: Waves

    Stop / go checkpoint

    Close rollback?

    Go when: Two release paths and all checks pass.

    Stop when: A critical source write or integration remains.

07The point of change

Cut over with a way back.

Go live

Cutover

Make GitHub the only writable code and CI control plane.

Recommended window: A low-release Friday with staffed verification.

  1. Freeze each Server/Data Center repository before its GEI migration and keep it frozen through reconciliation; freeze Cloud before its final mirror.
  2. Transfer the scoped Git refs and LFS objects through the selected route.
  3. Rotate secrets and switch CI.
  4. Switch remotes, webhooks, apps, and deployment keys.
  5. Run policy and release tests.
  6. Lock Bitbucket.

Proof to capture: Scoped refs match and GitHub alone completes a protected release and rollback.

Return to safety

Rollback

Restore Bitbucket without losing GitHub commits.

Deadline: Within 72 hours.

  1. Freeze GitHub.
  2. Mirror new refs to quarantine.
  3. Push approved refs to Bitbucket.
  4. Restore pipelines, secrets, policy, and integrations.
  5. Run release tests.

Proof to capture: Bitbucket contains approved refs and completes the protected release path.

Rollback immediately when
  • Missing refs or LFS
  • Policy bypass
  • Production pipeline failure
  • Access exposure
  • Critical integration failure
08Verification report

Prove the migration worked.

Every blocking check must pass. Capture the evidence before cleanup begins.

0%
Interactive report preview0 / 8 checks passed
PassIDCheckMethodExpected resultEvidence
V-01BlockingApproved user refsCompare only approved branch and tag tips, classify provider-owned refs separately, and run fsck.Exact parity for the approved user-ref scope.Ref diff.
V-02BlockingObjectsCompare inventories and downloads.Every pointer resolves.LFS report.
V-03BlockingRoute-specific metadataFor Server/Data Center GEI, reconcile pull requests, comments, reviews, attachments, and mannequins before lifting the freeze; for Cloud, verify the approved archive disposition.Every scoped metadata class is migrated through GEI or explicitly archived for the Cloud source-only route.Metadata report.
V-04BlockingMembershipTest role accounts.Least privilege.Access matrix.
V-05BlockingMerge controlsAttempt forbidden actions.All are blocked.Negative tests.
V-06BlockingRelease pathRun build through rollback.Approved result.Workflow runs.
V-07BlockingBinary availabilityCompare checksums.Critical assets match.Asset manifest.
V-08BlockingEvent deliveryTrigger each integration.One GitHub event.Delivery log.
09Post-migration cleanup

Remove the scaffolding safely.

Safe after: Two successful releases and 30 stable days.

  1. Archive mirrors and evidence.
  2. Revoke Bitbucket tokens and keys.
  3. Remove old runners and webhooks.
  4. Keep Bitbucket read-only through retention.
  5. Update development documentation.
  6. Schedule quarterly access, policy, secret, and restore reviews.
10Experiences from the field

When the plan met reality.

First-hand accounts are preferred. Vendor case studies are labeled, and every note below is an editorial paraphrase—follow the link for the full context.

First-person accountBrian · Sonar Community

Our organization is bound to Bitbucket and we migrated to GitHub2025

A team that completed its Bitbucket-to-GitHub move discovered that its SonarQube Cloud organization remained bound to Bitbucket. The apparent solution was to create a new organization, but community guidance documented a less obvious account and administrator handoff that could preserve the existing setup. The report is a compact example of a downstream integration retaining source-platform identity after repositories have moved.

What they recommend
  • Inventory security, quality, deployment, and identity services that are bound to the Bitbucket organization rather than individual repositories.
  • Test destination authentication for every organization administrator before revoking Bitbucket access or deleting the source workspace.
Worth noticing
  • Repository migration completed before the surrounding code-quality organization had a valid destination identity and ownership path.
  • The required fix depended on login order and administrator assignment, making it easy to miss in a repository-focused checklist.
Sources and evidence

Verify against the primary material.

Platform behavior changes. Check these sources and the review dates above before executing a production migration.

  1. GitHub: migration paths to GitHubAccessed 2026-07-27
  2. GitHub: migrate Bitbucket PipelinesAccessed 2026-07-27
  3. GitHub: import external Git repositoryAccessed 2026-07-27
  4. GitHub: Bitbucket Server and Data Center migration coverageAccessed 2026-07-27
  5. GitHub: Bitbucket Server and Data Center migration overviewAccessed 2026-07-27