bb2gh 0.14.2

CLI tool for migrating Bitbucket repositories to GitHub Enterprise

bb2gh

Bitbucket to GitHub migration tool. Migrate repositories with full metadata preservation, including Pull Requests, comments, user attribution, and secrets.

Features

• Terraform-inspired workflow: discover -> plan -> migrate -> validate
• Full metadata preservation: Git history, branches, tags, PRs, comments, user attribution
• LFS support: Automatic detection and migration of LFS objects
• Secrets migration: Assisted secrets migration via Infisical integration
• Enterprise ready: Supports GitHub Enterprise Cloud, Data Residency, and Enterprise Server
• Resilient: Checkpoint and resume capability, plus rollback options

Requirements

• Python 3.11 or newer
• git and git-lfs available in PATH

Installation

# Using pipx (recommended for CLI tools)
pipx install bb2gh

# Using pip
pip install bb2gh

PyPI and GitHub Releases are the supported public release channels.

The private repository builds the hardened bundle, and the public repository owns the visible GitHub Release and PyPI publication for that exact wheel.

If you need the exact published wheel, download it from GitHub Releases and verify it with the release checksums:

# Linux
sha256sum -c SHA256SUMS

# macOS
shasum -a 256 -c SHA256SUMS

On Windows PowerShell, use Get-FileHash for the downloaded wheel and compare it with the matching entry in SHA256SUMS.

Source-install from the public repository is unsupported in the hardened public release path. Homebrew is paused until a hardened formula exists.

Setup

Option 1: Interactive login

# Install with keyring support
pip install bb2gh[secure]

# Run interactive setup
bb2gh auth login

# Verify your setup
bb2gh auth status

Option 2: Environment variables

# Bitbucket
export BB_USERNAME=your-username
export BB_API_TOKEN=your-api-token

# GitHub
export GH_TOKEN=ghp_your-token

Required permissions

Bitbucket API token scopes: repository:read, pullrequest:read

GitHub PAT permissions: Contents (write), Pull requests (write), Administration (write), Metadata (read)

Quick Start

# 1. Discover your Bitbucket workspace
bb2gh discover --workspace my-company --output inventory.json

# 2. Generate a migration plan
bb2gh plan --inventory inventory.json --target-org my-gh-org --output plan.json

# 3. Execute the migration
bb2gh migrate --plan plan.json

# 4. Validate the migration
bb2gh validate --migration mig_xxx

Documentation

Full documentation is available at n8-group.gitbook.io/bb2gh.

• Getting Started Guide
• Command Reference
• Configuration Reference
• User Mapping Guide
• Enterprise Features

Reporting Issues

• Bug reports: https://github.com/n8group-oss/bb2gh/issues/new?template=bug_report.yml
• Feature requests: https://github.com/n8group-oss/bb2gh/issues/new?template=feature_request.yml
• Security vulnerabilities: https://github.com/n8group-oss/bb2gh/blob/main/SECURITY.md

License

Business Source License 1.1. See LICENSE for details.