# Introduction

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

* **Get Started in 5 Minutes**

  Install bb2gh and run your first migration with a simple four-step workflow.

  [Getting started](/bb2gh/getting-started/installation.md)
* **Full Git History**

  Preserve complete Git history including branches, tags, and all commits with proper attribution.

  [Learn more](/bb2gh/guides/guides.md)
* **PR & Review Preservation**

  Migrate Pull Requests with all comments, reviews, and approval history intact.

  [PR Migration](/bb2gh/guides/pr-migration.md)
* **Enterprise Ready**

  Support for GitHub Enterprise Cloud, Data Residency, and Enterprise Server deployments.

  [Enterprise](/bb2gh/guides/enterprise.md)

## Why bb2gh?

Moving from Bitbucket to GitHub is more than just pushing code. You need to preserve:

* **Pull Request history** — All PRs, comments, and reviews
* **User attribution** — Map Bitbucket users to GitHub accounts
* **Branch protections** — Convert Bitbucket restrictions to GitHub rules
* **Secrets** — Migrate pipeline variables securely
* **LFS objects** — Handle large files correctly

bb2gh handles all of this with a **Terraform-inspired workflow**:

```bash
# 1. Discover what you have
bb2gh discover --workspace my-company --output inventory.json

# 2. Plan the migration (review before executing)
bb2gh plan --inventory inventory.json --target-org my-gh-org --output plan.json

# 3. Execute with confidence
bb2gh migrate --plan plan.json

# 4. Verify everything worked
bb2gh validate --migration mig_xxx
```

## Quick Links

* [Installation Guide](/bb2gh/getting-started/installation.md) — Get bb2gh installed on your system
* [Command Reference](/bb2gh/commands/commands.md) — Detailed documentation for all commands
* [User Mapping Guide](/bb2gh/guides/user-mapping.md) — Configure user attribution
* [bb2gh.dev](https://bb2gh.dev) — Landing page & overview

## Contributing

Want to contribute? See the [Contributing Guide](https://github.com/n8group-oss/bb2gh/blob/main/CONTRIBUTING.md) on GitHub.

## Licensing

bb2gh requires a free license to operate. Register in seconds — no credit card required:

```bash
bb2gh license register --email you@company.com
```

See [Licensing](/bb2gh/getting-started/licensing.md) for setup details and [Plans & Features](/bb2gh/guides/plans-and-features.md) for plan comparison.

## Source License

bb2gh is licensed under the [Business Source License 1.1](https://github.com/n8group-oss/bb2gh/blob/main/LICENSE/README.md). You can use it freely for any purpose except offering a competing migration service. After 4 years from each release, that version converts to Apache 2.0.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://n8-group.gitbook.io/bb2gh/getting-started/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.