Migrate Bitbucket repositories to Forgejo

Plan a Bitbucket-to-Forgejo move across Git refs, pull-request history, LFS, permissions and CI, with source-specific importer checks and rollback evidence.

Last updated

In short

  • Distinguish Bitbucket Cloud from Data Center before choosing an importer.
  • Git refs transfer separately from review history and CI configuration.
  • Preserve source IDs and reconcile new work before rollback.
On this page (7)

Migration plans · Part of Forgejo

Identify which Bitbucket product is the source

Bitbucket Cloud and Bitbucket Data Center have different APIs, authentication and migration behavior. Record the source product and version before selecting a Forgejo importer. A guide for one should not be assumed to preserve the same review objects from the other.

This is a reference migration and acceptance plan, not an executed import. Forgejo’s v17 release announcement specifically introduces Bitbucket Data Center migration with pull requests, reviews and comments, subject to its documented access requirements. That is a version-specific capability, not evidence that every older Forgejo release or Cloud import has equivalent coverage.

Inventory Git and collaboration data separately

Object Migration treatment Fidelity check
Branches and tags Git transfer through selected importer or reviewed mirror process Ref names and commit hashes
LFS objects Separate verification of object transfer Download representative large files
Pull requests and reviews Source-specific importer coverage State, participants, comments and diff references
Issues and wiki Verify selected source/target support Content, links and attachments
Users and permissions Rebuild identities and organization/team access Positive and negative repository access
Branch restrictions Recreate supported rules Protected branch rejects unauthorized push
Pipelines Rebuild for selected CI engine Equivalent test and release outcome
Secrets and deploy keys Reissue with minimum scope Old credentials retired deliberately
Webhooks and integrations Reconfigure endpoints No duplicate external actions

The Bitbucket Cloud repository API exposes repository metadata, permissions and hooks through separate resources. A Git clone does not contain those settings. Preserve an inventory of them even when the repository’s refs transfer perfectly.

Establish identity and attribution rules

Create destination users and teams before opening imported repositories to work. Map source identities to destination identities using stable source IDs and verified ownership. Some historical contributors may no longer have active accounts; decide how their attribution will be retained without granting them access.

Distinguish commit authorship from platform identity. Git commits retain author strings in the repository, while pull-request participants and permission assignments are application records. A matching commit author name is not evidence that the correct Forgejo user owns the review history.

Keep repositories private during rehearsal. Use a test maintainer, contributor and outsider to validate organization membership, repository visibility and branch restrictions. Review inherited access and public visibility explicitly.

Rehearse a representative repository

Choose a repository with several branches and tags, an open pull request, a merged review with inline comments, an attachment or wiki link, LFS content and a working pipeline. Record the source product, Forgejo release and exact migration options used.

For Data Center migration on a supporting Forgejo release, verify the documented HTTP-token and HTTPS clone prerequisites. For Cloud, inspect the actual available migration source and its coverage in the selected release; do not infer Data Center review-history support. If an object cannot be imported, retain a readable archive or rebuild it under an agreed fidelity exception.

Compare ref sets and hashes, then sample review threads and linked files. Open historical links and identify which need rewriting or a source archive. Record skipped or failed objects with source IDs so the team can distinguish known loss from an unnoticed incomplete import.

Rebuild CI as a separate project

Bitbucket Pipelines configuration is not a guarantee of equivalent behavior in Forgejo Actions or another CI system. Translate the build steps, dependency caches, artifacts, deployment approvals and secret use into the selected runner environment.

Use the Forgejo Actions security guide when deciding runner privileges and network access. Untrusted contributions should not inherit release credentials. Validate the resulting workflow with synthetic test and deployment targets before enabling production releases.

Record the Forgejo and runner releases, base images, action revisions and applicable licences. Pin third-party action references appropriately and review the code that receives secrets. A successful source import should not automatically execute unreviewed pipeline content.

Cut over at a known write boundary

Announce a freeze or another explicit final-change policy. Capture the final source refs and collaboration-object inventory, complete the supported transfer and reconcile changes made after rehearsal. Disable source webhooks and scheduled automation before enabling equivalent target actions.

Cutover gate Required evidence
Git Required refs match expected hashes
LFS Referenced objects are retrievable
Reviews Agreed sample and known exceptions accepted
Permissions Outsider denied; contributor and maintainer scoped correctly
CI Test and release paths behave as approved
Integrations Correct endpoint and single active owner
Recovery Forgejo backup includes repositories, database, files and secrets

Update developer remotes, package references and documentation links through a checklist. Keep the source available in a controlled read-only or archival role for the agreed period where possible.

Roll back with both histories preserved

Before target writes begin, rollback can return users to the unchanged source. Afterward, new commits and review discussions must be reconciled. Preserve both repositories and export the new target-only application records before changing the authoritative location.

Stop target automation before reactivating the source. Revoke temporary migration tokens and rotate deployment credentials according to the agreed ownership plan. Accept the migration only after repository fidelity, collaboration exceptions, permissions, CI and backup recovery are reviewed. That avoids mistaking a successful clone for a completed development-platform move.

Sources and further reading

Use the linked documentation to confirm the version, edition and contract that apply to your project.

Scope our Bitbucket exit

Bring the Bitbucket product/version, repository inventory, required review history and CI dependencies.