bb2gh 0.5.4
CLI tool for migrating Bitbucket repositories to GitHub Enterprise
Requires Python: >=3.11
Keywords: bitbucket, cli, devops, github, migration

# bb2gh

[![CI](https://github.com/n8group-oss/bb2gh/actions/workflows/ci.yml/badge.svg)](https://github.com/n8group-oss/bb2gh/actions/workflows/ci.yml)
[![Security](https://github.com/n8group-oss/bb2gh/actions/workflows/security.yml/badge.svg)](https://github.com/n8group-oss/bb2gh/actions/workflows/security.yml)
[![Documentation](https://img.shields.io/badge/docs-GitBook-blue.svg)](https://n8-group.gitbook.io/bb2gh/)
[![License: BSL-1.1](https://img.shields.io/badge/License-BSL--1.1-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

**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/resume capability, rollback options

## Requirements

- Python >= 3.11
- Git and git-lfs available in PATH

## Installation

```bash
# Using pip
pip install bb2gh

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

## Setup

### Option 1: Interactive login (recommended)

The fastest way to get started. Stores secrets securely in your OS keychain:

```bash
# Install with keyring support
pip install bb2gh[secure]

# Run interactive setup — prompts for Bitbucket and GitHub credentials
bb2gh auth login
```

The login flow will:
1. Ask for your Bitbucket username and API token (or OAuth2 credentials)
2. Ask for your GitHub personal access token (or GitHub App details)
3. Validate credentials against the APIs
4. Store secrets in your OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
5. Save non-secret config to `~/.bb2gh/config.yaml`

Verify your setup:

```bash
bb2gh auth status
```

### Option 2: Environment variables (CI/CD)

For headless environments, pipelines, or Docker:

```bash
# Bitbucket — create an API token at:
# https://id.atlassian.com/manage-profile/security/api-tokens
export BB_USERNAME=your-username
export BB_API_TOKEN=your-api-token

# GitHub — create a fine-grained PAT at:
# https://github.com/settings/personal-access-tokens/new
export GH_TOKEN=ghp_your-token
```

> **Note**: Bitbucket App Passwords are deprecated and will stop working in June 2026. Use API tokens instead — they work the same way (HTTP Basic auth) with the same username. See the [Authentication Guide](https://n8-group.gitbook.io/bb2gh/getting-started/authentication) for details.

### Required permissions

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

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

## Quick Start

```bash
# 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
```

## Development

```bash
# Clone the repository
git clone https://github.com/n8group-oss/bb2gh.git
cd bb2gh

# Install Hatch (build system / environment manager)
pip install hatch

# Create the development environment (installs Python 3.11+ and all dependencies)
hatch env create

# Install pre-commit hooks
hatch run pre-commit install

# Run tests
hatch run test

# Run tests with coverage
hatch run test-cov

# Run linting
hatch run lint

# Run type checking
hatch run type-check

# Run all checks (lint + format-check + type-check + tests)
hatch run all
```

## Documentation

Full documentation is available at **[n8-group.gitbook.io/bb2gh](https://n8-group.gitbook.io/bb2gh/)**

- [Getting Started Guide](https://n8-group.gitbook.io/bb2gh/getting-started/installation)
- [Command Reference](https://n8-group.gitbook.io/bb2gh/commands)
- [Configuration Reference](https://n8-group.gitbook.io/bb2gh/getting-started/configuration)
- [User Mapping Guide](https://n8-group.gitbook.io/bb2gh/guides/user-mapping)
- [Enterprise Features](https://n8-group.gitbook.io/bb2gh/guides/enterprise)

## License

Business Source License 1.1 - see [LICENSE](LICENSE) for details.

The license allows free use for any purpose except offering a competing migration service. After 4 years from each release, that version converts to Apache 2.0.

## Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) before submitting a PR.