Development migration

Bitbucket → GitHub

Move Bitbucket repositories to GitHub with verified Git history, LFS, identities, pull-request context, branch policy, pipelines, secrets, webhooks, deployment keys, and a mirror-based rollback.

Typical timeline15–30 business days60–110 hours active work

Statusneeds review

Source testedBitbucket Cloud and Data Center paths reviewed 2026-07-19

Destination testedGitHub migration guidance reviewed 2026-07-19

Last reviewed2026-07-19

Sources3

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.

01At a glance

Know the shape of the move.

Transfer outcome10 features audited

Clean1

Partial3

Manual4

Lost2

Mapping route7 of 8 fields have a destination path

SourceBitbucket8 mapped fields

Automatic2

Transform2

Manual3

Unsupported1

DestinationGitHub7 supported paths

This timeline assumes

Up to 100 repositories with Git, LFS, Pipelines, and common integrations.
Bitbucket Cloud uses source-and-history migration; Bitbucket Server/Data Center 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.

02Loss matrix

What survives the move.

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

Item	Outcome	Impact	What happens	Mitigation
Git commits, branches, and tags	clean	critical	Mirror clone and push preserve Git history and refs.	Compare every ref tip and run fsck.
Git LFS objects	partial	critical	LFS requires an explicit fetch and transfer.	Compare LFS object inventories and checksums.
Pull requests and comments	partial	high	Cloud source-and-history paths do not carry all collaboration metadata.	Archive required history or use the supported enterprise path where eligible.
Issues and wiki	manual	high	They require separate migration or archival paths.	Export issues and mirror the wiki repository.
Users and groups	manual	critical	Workspace membership and permissions do not map automatically.	Pre-create teams and identity mapping.
Branch restrictions and merge checks	manual	critical	Policy semantics differ.	Rebuild rulesets, protections, reviews, and CODEOWNERS from intent.
Bitbucket Pipelines	partial	critical	GitHub Actions Importer can convert workflows, but manual validation remains.	Audit, dry-run, review, and exercise every release path.
Secrets and deployment variables	lost	critical	Secret values do not transfer safely.	Rotate into protected GitHub environments and secrets.
Downloads, packages, and artifacts	manual	high	Binary assets and registries have separate paths.	Inventory, copy, checksum, and test consumers.
Webhooks, apps, keys, and integrations	lost	critical	Installation and credential state is platform-specific.	Reauthorize or replace each integration.

03Field and feature mapping

Where each thing goes.

Source	Destination	Method	Notes
Workspace/project	Organization/team	manual	Design namespace and access first.
Repository	Repository	automatic	Confirm visibility and default branch.
Git refs	Git refs	automatic	Use mirror semantics.
Bitbucket user	GitHub user/team	transform	Map verified identities.
Branch restriction	Ruleset/branch protection	manual	Rebuild and negative-test.
bitbucket-pipelines.yml	.github/workflows/*.yml	transform	Use Actions Importer then review.
Deployment variable	Environment secret	manual	Rotate values.
Webhook/app	No destination	unsupported	Reinstall or replace.

04Before you begin

Make the move recoverable.

Backup procedure

Create the source-of-truth backup

Preserve repositories and every operational dependency.

Inventory repos, refs, LFS, wikis, PRs, issues, policies, pipelines, runners, secrets, artifacts, and integrations.
Mirror clone repos and wikis, fetch all LFS, and run fsck.
Export collaboration counts and required metadata.
Checksum assets and record secret names/consumers.
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.

Audit pipelines.
Run dry-run conversion.
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.

Map users and teams.
Map restrictions to rulesets.
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 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 forUp to 100 repositories

Total elapsed15–30 business days

Active work60–110 hours

BufferAdd time for complex pipelines, large LFS, or enterprise metadata migration.

Days 1–4Inventory4 days

Days 5–7Mirrors3 days

Days 8–12Pilot5 days

Days 13–22Migration waves6–10 days

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
- Migrate by dependency.
- Reconcile each repo and integration.
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
- Freeze and mirror final refs.
- Switch CI, remotes, webhooks, and deploys.
- Observe releases.
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.

Freeze Bitbucket writes and deploys.
Mirror final Git and LFS refs.
Rotate secrets and switch CI.
Switch remotes, webhooks, apps, and deployment keys.
Run policy and release tests.
Lock Bitbucket.

Proof to capture: 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.

Freeze GitHub.
Mirror new refs to quarantine.
Push approved refs to Bitbucket.
Restore pipelines, secrets, policy, and integrations.
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.

ID	Check	Method	Expected result	Evidence
`V-01`Blocking	Refs	Compare all tips and fsck.	Exact parity.	Ref diff.
`V-02`Blocking	Objects	Compare inventories and downloads.	Every pointer resolves.	LFS report.
`V-03`Blocking	PRs, issues, and wiki	Reconcile counts or archive disposition.	100% accounted for.	Metadata report.
`V-04`Blocking	Membership	Test role accounts.	Least privilege.	Access matrix.
`V-05`Blocking	Merge controls	Attempt forbidden actions.	All are blocked.	Negative tests.
`V-06`Blocking	Release path	Run build through rollback.	Approved result.	Workflow runs.
`V-07`Blocking	Binary availability	Compare checksums.	Critical assets match.	Asset manifest.
`V-08`Blocking	Event delivery	Trigger each integration.	One GitHub event.	Delivery log.

09Post-migration cleanup

Remove the scaffolding safely.

Safe after: Two successful releases and 30 stable days.

Archive mirrors and evidence.
Revoke Bitbucket tokens and keys.
Remove old runners and webhooks.
Keep Bitbucket read-only through retention.
Update development documentation.
Schedule quarterly access, policy, secret, and restore reviews.

Sources and maintenance

Built to be reviewed.

Tested 2026-07-19. Next scheduled review: 2026-10-19.

GitHub: migration paths to GitHubAccessed 2026-07-19
GitHub: migrate Bitbucket PipelinesAccessed 2026-07-19
GitHub: import external Git repositoryAccessed 2026-07-19

Know the shape of the move.

This timeline assumes

What survives the move.

Where each thing goes.

Make the move recoverable.

Create the source-of-truth backup

CI conversion

Policy and identity map

The things most likely to hurt.

Repositories diverge

CI permissions broaden

Policy disappears

Do the work in this order.

Inventory

Back up?

Mirrors

Pilot?

Pilot

Waves?

Migration waves

Cut over?

Final mirror and observation

Close rollback?

Cut over with a way back.

Cutover

Rollback

Prove the migration worked.

Remove the scaffolding safely.

Built to be reviewed.