Metadata-Version: 2.4
Name: bb2gh
Version: 0.19.0
Summary: CLI tool for migrating Bitbucket repositories to GitHub Enterprise
Project-URL: Documentation, https://n8-group.gitbook.io/bb2gh/
Project-URL: Homepage, https://bb2gh.dev
Project-URL: Issues, https://github.com/n8group-oss/bb2gh/issues
Project-URL: Repository, https://github.com/n8group-oss/bb2gh
Project-URL: Changelog, https://github.com/n8group-oss/bb2gh/blob/main/CHANGELOG.md
Author-email: N8 Group <contact@n8-group.com>
Maintainer-email: Marcin Noczynski <marcin.noczynski@n8-group.com>
License-Expression: BUSL-1.1
License-File: LICENSE
Keywords: bitbucket,cli,devops,github,migration
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: cryptography>=43.0.0
Requires-Dist: gitpython>=3.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: migration-core[github-app]<1.0.0,>=0.1.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: posthog>=7.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: structlog>=24.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: cleanup
Requires-Dist: git-filter-repo>=2.38.0; extra == 'cleanup'
Provides-Extra: enterprise
Requires-Dist: redis>=5.0.0; extra == 'enterprise'
Requires-Dist: rq>=1.16.0; extra == 'enterprise'
Provides-Extra: secure
Requires-Dist: keyring>=25.0.0; extra == 'secure'
Description-Content-Type: text/markdown

# bb2gh

[![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 and resume capability, plus rollback options

## Requirements

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

## Installation

```bash
# 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](https://github.com/n8group-oss/bb2gh/releases) and verify it
with the release checksums:

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

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

# Run interactive setup
bb2gh auth login

# Verify your setup
bb2gh auth status
```

### Option 2: Environment variables

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

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

## 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)

## 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](https://github.com/n8group-oss/bb2gh/blob/main/LICENSE) for details.
