migrating.toBrowse playbooks
← All playbooks
Code hosting migration

Bitbucket → GitLab

Move Bitbucket repositories, branches, pull requests, issues, users, wikis, LFS data, pipelines, permissions, deployments, and integrations into GitLab with route-specific importer and identity checks.

Typical timeline12–26 business days58–110 hours active work
Statusneeds review
Source testedBitbucket documentation reviewed 2026-07-19
Destination testedGitLab documentation 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

GitLab

What gets better
  • A comprehensive DevSecOps platform offers deep CI/CD and self-hosting options
  • Repository-centered workflows keep code, review, and automation close together
What gets worse
  • Breadth, upgrades, and administration can be heavy for smaller teams
  • Advanced governance and automation can become configuration-heavy
Best of the move

GitLab: A comprehensive DevSecOps platform offers deep CI/CD and self-hosting options. 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: Breadth, upgrades, and administration can be heavy for smaller teams.

Connected catalog

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

Also from Bitbucket
01At a glance

Know the shape of the move.

Transfer outcome12 features audited
Transfer outcome distributionClean transfer: 2, Partial transfer: 7, Manual rebuild: 3, Not transferred: 0.
Clean2
Partial7
Manual3
Lost0
Mapping route9 of 9 fields have a destination path

This timeline assumes

  • Up to 100 repositories, 500 GB of Git data, and 250 users
  • Administrators control both platforms, identity mapping, DNS, registries, and every repository integration.
  • A representative repository set is migrated into an isolated destination organization first.
  • The source remains read-only until developers and automation pass one complete release cycle.
  • The migration team records evidence for every blocking verification check.
02Loss matrix

What survives the move.

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

ItemOutcomeImpactWhat happensMitigation
Git repositories, branches, and tagscleancriticalGitLab’s Bitbucket importer and Git mirror paths can preserve core repository history.Compare refs, commit graphs, default branches, submodules, and LFS objects.
Pull requests, issues, comments, and userspartialcriticalCoverage and attribution differ by Bitbucket Cloud versus Data Center and by reachable user identity.Pilot each source type and preserve original IDs, URLs, authors, and timestamps.
Bitbucket Pipelines and deploymentsmanualcriticalPipeline definitions, variables, caches, artifacts, and deployment gates do not execute as GitLab CI automatically.Translate each active pipeline and run equivalent release rehearsals.
Workspace permissions, Jira links, apps, and webhooksmanualcriticalBitbucket workspace configuration does not map directly to GitLab groups and integrations.Design groups and roles, rotate credentials, and enable integrations one at a time.
Git repositories and commit historycleancriticalGit source, branches, tags, and commits can move through supported importers or mirror pushes.Compare refs, commit graphs, default branches, submodules, signatures, and shallow state.
Pull or merge requestspartialcriticalMetadata migration depends on the selected importer and supported source version.Pilot open, closed, merged, draft, forked, and large requests.
Issues, comments, and discussionspartialhighCoverage, formatting, attribution, timestamps, and cross-links vary by migration path.Preserve source IDs and URLs and reconcile representative conversations.
Users and contribution attributionpartialcriticalEmail and username differences can create placeholders or migration identities.Freeze an identity map and reclaim or annotate unmapped activity.
Git LFS and large binariespartialcriticalGit history can move while LFS objects, package blobs, and releases require separate transfer.Inventory object counts and compare hashes after migration.
Branches, tags, and protectionspartialcriticalRefs move more easily than approval, push, merge, and signing policies.Recreate rules before developers receive write access.
CI/CD pipelines and secretsmanualcriticalPipeline syntax, runners, caches, artifacts, environments, and secret stores differ.Translate and rehearse every active build and release workflow.
Packages, containers, and releasespartialhighRegistries and release assets do not necessarily follow repository data.Copy immutable artifacts and update package coordinates and credentials.
03Field and feature mapping

Where each thing goes.

SourceDestinationMethodNotes
Bitbucket repositoryGitLab repositoryautomaticPreserve stable source URL and default branch.
Git branch and tagGit branch and tagautomaticCompare all refs after import.
Pull or merge requestDestination pull or merge requesttransformDepends on selected metadata importer.
Issue and commentDestination issue and commenttransformPreserve author, timestamp, ID, and URL.
Source userDestination identitymanualFreeze an identity map before migration.
Branch protectionDestination ruleset or branch restrictionmanualRebuild before write access.
CI pipelineDestination workflowtransformReview every generated or translated step.
Package, release, or LFS objectDestination registry, release, or LFS objecttransformCopy binaries and compare hashes.
Group, team, or permissionDestination organization, team, and rolemanualApply least privilege.
04Before you begin

Make the move recoverable.

Backup procedure

Create the source-of-truth backup

Preserve Bitbucket data, configuration, and operating evidence before any destination write.

  1. Inventory and export Bitbucket repositories, metadata, users, permissions, pipelines, packages, releases, webhooks, and settings.
  2. Mirror every Git repository and fetch Git LFS objects.
  3. Record counts by repository, ref, pull request, issue, user, package, and integration.
  4. Hash archives and migration manifests.

Proof to capture: A signed manifest reconciles every scoped record class, runtime dependency, export file, count, and hash.

Transformation · Platform inventory tools and migration workbook

Repository and identity manifest

Preserve repository scope, Git refs, users, and metadata ownership.

  1. Inventory source values and exceptions.
  2. Define explicit destination mappings.
  3. Reject unmapped critical records.

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

Transformation · Official importer, CI converter, and verification scripts

Workflow and integration conversion

Rebuild delivery and connected services safely.

  1. Normalize encoding, dates, identifiers, and blanks.
  2. Run a representative pilot.
  3. Reconcile accepted, rejected, and transformed rows.

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.

Migration

A code-only move is mistaken for a metadata migration

criticalpossible likelihood

Git refs exist while pull requests, issues, users, or settings are missing.

Consequence
Collaboration and control history disappears.
Mitigation
Choose and verify the required migration fidelity explicitly.

Stop if: Any required metadata class lacks a supported path.

Cutover

Both platforms accept writes

criticalpossible likelihood

Developers or bots push and update work in both systems.

Consequence
Repositories and release state diverge.
Mitigation
Freeze source writes and change remotes in one controlled window.

Stop if: Any unapproved source writer remains active.

Access

Permissions or secrets are over-broad

criticalpossible likelihood

Migrated users or automation receive more authority than intended.

Consequence
Code, packages, or production systems are exposed.
Mitigation
Apply least privilege before opening repositories.

Stop if: An unauthorized test identity can perform a protected action.

06Precise timeline

Do the work in this order.

Estimate forUp to 100 repositories, 500 GB of Git data, and 250 users
Total elapsed12–26 business days
Active work58–110 hours
BufferAdd time for Bitbucket Data Center, large LFS stores, many Pipelines, Jira coupling, or complex workspace permissions.
01
Days 1–3Inventory and decisions2–3 days
02
Days 3–5Backup and reconcile1–3 days
03
Days 5–12Map and pilot3–8 days
04
Days 10–20Final delta and switch1–5 days
05
Days 12–40Observe and close3–10 days
  1. Days 1–3 · inventory

    Inventory and decisions

    6–12 hours active2–3 days elapsedOwner review waiting
    • Inventory Bitbucket data, features, users, domains, and integrations.
    • Approve scope, owners, mappings, and exclusions.

    Depends on: Bitbucket and GitLab administrator access

    Stop / go checkpoint

    Export?

    Go when: Every critical item has an owner and disposition.

    Stop when: Consent, billing, access, or system ownership is unclear.

  2. Days 3–5 · backup

    Backup and reconcile

    5–10 hours active1–3 days elapsedExport processing waiting
    • Create immutable exports and configuration evidence.
    • Reconcile counts, totals, and hashes.

    Depends on: Approved inventory

    Stop / go checkpoint

    Transform?

    Go when: Source totals and export manifests agree.

    Stop when: Any critical dataset or configuration is absent.

  3. Days 5–12 · pilot

    Map and pilot

    10–35 hours active3–8 days elapsedDestination processing and review waiting
    • Configure GitLab and transform representative data.
    • Run a pilot containing normal records and every critical edge case.

    Depends on: Verified backup

    Stop / go checkpoint

    Scale?

    Go when: Pilot mappings, behavior, access, and evidence pass.

    Stop when: Any critical check fails or produces unexplained variance.

  4. Days 10–20 · cutover

    Final delta and switch

    5–25 hours active1–5 days elapsedDNS, import, or sync propagation waiting
    • Freeze production writes in Bitbucket.
    • Apply the final delta, switch ownership, and run blocking checks.

    Depends on: Passed pilot and approved rollback

    Stop / go checkpoint

    Open production?

    Go when: Counts reconcile and one destination system owns production.

    Stop when: A source writer remains active or a blocking check fails.

  5. Days 12–40 · observe

    Observe and close

    3–18 hours active3–10 days elapsedOperating-cycle evidence waiting
    • Monitor one complete operating cycle.
    • Sign the verification report and close rollback only after stability.

    Depends on: Verified cutover

    Stop / go checkpoint

    Close rollback?

    Go when: No trigger occurs during the agreed observation period.

    Stop when: Data, access, delivery, routing, or business results regress.

07The point of change

Cut over with a way back.

Go live

Cutover

Make GitLab the only production system without losing the final Bitbucket delta.

Recommended window: A low-volume weekday morning with platform, data, DNS, and business owners available.

  1. Freeze production writes and scheduled actions in Bitbucket.
  2. Export, transform, and reconcile the final delta.
  3. Apply the approved delta to GitLab.
  4. Switch domains, forms, integrations, sending, or sync ownership as applicable.
  5. Run every blocking verification check and keep the source intact.

Proof to capture: GitLab owns production, totals reconcile, and every blocking check has durable evidence.

Return to safety

Rollback

Return production ownership to Bitbucket without losing destination-era changes.

Deadline: Within seven days and before source data, plans, credentials, domains, or billing are changed.

  1. Stop new writes and scheduled actions in GitLab.
  2. Restore the prior Bitbucket routing, forms, integrations, sending, or sync ownership.
  3. Export the GitLab post-cutover delta.
  4. Review and apply safe destination-era changes to Bitbucket.
  5. Run the same blocking checks against the restored source.

Proof to capture: Bitbucket again owns production with current data and no duplicate destination action.

Rollback immediately when
  • Unexplained critical count or value variance
  • Missing or exposed critical data
  • Duplicate production action
  • Failed access, routing, delivery, or integration check
  • A critical feature has no safe destination replacement
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-01BlockingRepository and ref parityCompare repositories, commits, branches, tags, default branches, submodules, and LFS.Every scoped Git object is accounted for.Git manifest.
V-02BlockingCollaboration coverageCompare pull requests, issues, comments, releases, wikis, and projects by source class.Every required item is migrated or explicitly archived.Metadata ledger.
V-03BlockingAttribution mappingInspect active, inactive, bot, and external contributors.Every required author has a destination or annotation.Identity map.
V-04BlockingTeams and repository rulesTest representative users and protected actions.Least privilege and branch controls match policy.Access report.
V-05BlockingBuild and release parityRun representative workflows from identical commits.Tests, artifacts, approvals, and deployments match.Workflow evidence.
V-06BlockingPackages, releases, and LFSCompare counts, coordinates, sizes, and hashes.Every required binary is present and retrievable.Artifact manifest.
V-07BlockingConnected servicesExercise each webhook, app, key, and notification.One correct destination callback per event.Integration log.
V-08BlockingSingle repository authorityInspect developer remotes, bots, and source protections.GitLab alone accepts approved writes.Cutover checklist.
09Post-migration cleanup

Remove the scaffolding safely.

Safe after: One complete operating cycle, at least seven stable days, and owner sign-off on every blocking check.

  1. Create final Bitbucket exports and archive verification evidence.
  2. Revoke temporary credentials, API keys, webhooks, and elevated roles.
  3. Remove obsolete embeds, forms, jobs, integrations, and DNS records.
  4. Keep the source intact through the approved retention window.
  5. Cancel paid plans only after billing, legal, and recovery review.
  6. Schedule the next GitLab backup, access, and migration-playbook review.
Sources and maintenance

Built to be reviewed.

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

  1. GitLab: import from Bitbucket CloudAccessed 2026-07-19
  2. Bitbucket Cloud: export repository dataAccessed 2026-07-19
  3. GitLab: project import and exportAccessed 2026-07-19