# Quick Start

This guide walks you through your first migration from Bitbucket to GitHub.

## Prerequisites

Before you begin, ensure you have:

1. **bb2gh installed** — See [Installation](/bb2gh/getting-started/installation.md)
2. **License activated** — Register for a free license (see [Licensing](/bb2gh/getting-started/licensing.md))
3. **Bitbucket credentials** — API token (Cloud) or Personal Access Token (Data Center) with repository read access (see [Authentication](/bb2gh/getting-started/authentication.md))
4. **GitHub credentials** — Personal access token or GitHub App (see [Authentication](/bb2gh/getting-started/authentication.md))

## Step 1: Configure Authentication

The easiest way to set up credentials is the interactive login:

```bash
bb2gh auth login
```

This stores secrets in your OS keychain and saves configuration to `~/.bb2gh/config.yaml`. See [Authentication](/bb2gh/getting-started/authentication.md) for the full walkthrough.

Alternatively, use environment variables:

```bash
# Bitbucket credentials
export BB_USERNAME="your-bitbucket-username"
export BB_API_TOKEN="your-api-token"

# GitHub credentials
export GH_TOKEN="your-github-token"
```

> **Note**: Bitbucket App Passwords are deprecated and will stop working in June 2026. Use API tokens instead. See [Authentication > Bitbucket](/bb2gh/getting-started/authentication.md#bitbucket-authentication) for migration steps.

## Step 2: Discover Your Repositories

Scan your Bitbucket workspace to create an inventory:

```bash
bb2gh discover \
  --workspace my-company \
  --output inventory.json
```

This creates `inventory.json` with details about all repositories including:

* Repository metadata (size, branches, tags)
* LFS status
* Open pull requests
* Migration complexity assessment

It also generates an HTML dashboard at `.bb2gh/reports/discovery-report.html` with charts, a sortable repository table, and warnings. Open it in your browser to review the workspace at a glance. See the [Discovery Report Guide](/bb2gh/guides/discovery-report.md) for details.

## Step 3: Create a Migration Plan

Generate a migration plan:

```bash
bb2gh plan \
  --inventory inventory.json \
  --target-org my-github-org \
  --user-mapping users.csv \
  --output plan.json
```

Review the plan before executing:

```bash
# View plan summary
cat plan.json | jq '.summary'

# List repositories to be migrated
cat plan.json | jq '.repositories[].name'
```

## Step 4: Execute the Migration

Run the migration:

```bash
bb2gh migrate --plan plan.json
```

For faster migrations, use parallel workers (Pro and Ultimate plans):

```bash
bb2gh migrate --plan plan.json --workers 4
```

The migration will:

1. Clone each repository from Bitbucket
2. Push to GitHub with full history
3. Migrate pull requests and comments
4. Configure branch protections
5. Set up repository settings

See the [Parallel Execution Guide](/bb2gh/guides/parallel-execution.md) for tuning parallel workers.

## Step 5: Validate the Migration

Verify everything migrated correctly:

```bash
bb2gh validate --migration mig_xxx
```

This checks:

* Commit count matches
* Branches and tags present
* Pull requests migrated
* User attribution correct

## Migrating from Bitbucket Data Center?

If you're migrating from Bitbucket Data Center instead of Cloud, see the [Bitbucket DC Migration Guide](/bb2gh/guides/bitbucket-dc.md). The workflow is the same — just use `--source bitbucket-dc` with the `discover` command and authenticate with a PAT.

## Next Steps

* [Bitbucket DC Migration](/bb2gh/guides/bitbucket-dc.md) — Migrate from Bitbucket Data Center
* [User Mapping Guide](/bb2gh/guides/user-mapping.md) — Configure user attribution
* [LFS Migration](/bb2gh/guides/lfs-migration.md) — Handle large files
* [Command Reference](https://github.com/n8group-oss/bb2gh/blob/main/docs/gitbook/commands/index.md) — Detailed command documentation


---

# 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/quickstart.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.