API Tokens Setup Guide

This comprehensive guide explains all authentication requirements for the Bitbucket to GitHub migration tools, including the audit script, migration script, and optional GitHub CLI integration.

---

🔑 Authentication Overview

The migration process requires multiple authentication methods depending on which tools you use:

Tool	Bitbucket Token	GitHub PAT	GitHub CLI	Purpose
migrate_bitbucket_to_github test-auth	✅ Required	✅ Required	❌ Optional	Test authentication
migrate_bitbucket_to_github audit	✅ Required	❌ Not needed	❌ Not needed	Audit repository content
migrate_bitbucket_to_github dry-run	✅ Required	✅ Required	❌ Optional	Dr-run migrate issues/PRs
migrate_bitbucket_to_github migrate	✅ Required	✅ Required	❌ Optional	Migrate issues/PRs
migrate_bitbucket_to_github migrate --use-gh-cli	✅ Required	✅ Required	✅ Required	Auto-upload attachments

Choose your path:

• Basic Migration: Bitbucket API Token + GitHub PAT
• Advanced Migration: All three authentication methods (for automatic attachment uploads)

---

🔑 Bitbucket Cloud API Token

Required for: migrate_bitbucket_to_github audit, migrate_bitbucket_to_github migrate

Creating Your Token

1. Go to Atlassian Account Settings → Security → Create and manage API tokens
2. Click Create API token
3. Name it: Migration Tool
4. Choose Bitbucket as the app
5. Set Full access (or minimally: read repos, issues, PRs)
6. Copy the token immediately – it won't be shown again

Required Permissions

{
  "scopes": [
    "repository:read",
    "pullrequest:read",
    "issue:read",
    "account:read"
  ]
}

Note: User-level API tokens (not Repository Access Tokens) are required for issue and PR access.

Usage in Configuration

"bitbucket": {
  "email": "you@example.com",
  "token": "SET_BITBUCKET_TOKEN_ENV_VAR"
}

Note: Tokens are no longer stored in config files. Set them via environment variables instead.

---

🔑 GitHub Authentication

Required for: migrate_bitbucket_to_github dry-run and migrate_bitbucket_to_github migrate

GitHub Personal Access Token (PAT)

Creating Your Token

1. Go to GitHub Settings → Developer settings → Personal access tokens (classic)
2. Click Generate new token (classic)
3. Name it Bitbucket Migration
4. Select scopes:
   • repo (Full control of private repositories)
   • user:email (Read-only access to email addresses)
5. Click Generate token and copy it

Required Scopes Explained

Scope	Purpose	Why Needed
repo	Full repository access	Create issues, PRs, comments, manage assignees
user:email	Read email addresses	User mapping and author identification

Usage in Configuration

"github": {
  "owner": "my-org",
  "repo": "my-repo",
  "token": "YOUR_GITHUB_TOKEN_HERE"
}

Note: Tokens are no longer stored in config files. Set them via environment variables instead.

GitHub CLI Authentication (Optional)

Required only for: --use-gh-cli flag (automatic attachment uploads)

Setup Instructions

1. Install GitHub CLI:

   # macOS
   brew install gh
   
   # Ubuntu/Debian
   sudo apt update && sudo apt install gh
   
   # Windows (using winget)
   winget install --id GitHub.cli
   
   # Other platforms: https://cli.github.com/
   

2. Authenticate GitHub CLI:

   gh auth login
   
   # Follow prompts:
   # - GitHub.com
   # - HTTPS
   # - Login with web browser
   # - Authorize GitHub CLI
   

3. Verify authentication:

   gh auth status
   

Important: GitHub CLI must be authenticated to the same GitHub account/organization as your PAT.

---

🔧 Token Security Best Practices

Environment Variables (Recommended)

# Create .env file
BITBUCKET_TOKEN=ATAT1234...
GITHUB_TOKEN=ghp_abcd123...

# Or set in shell
export BITBUCKET_TOKEN="ATAT1234..."
export GITHUB_TOKEN="ghp_abcd123..."

# Run scripts (tokens loaded automatically from env vars or .env)
migrate_bitbucket_to_github audit --workspace YOUR_WORKSPACE --repo YOUR_REPO --email you@example.com

Security Guidelines

• Never commit tokens to Git repositories
• Use environment variables or .env files for token storage (recommended)
• Use read-only tokens where possible (audit script only needs read access)
• Rotate tokens regularly (especially after migration completion)
• Use separate tokens for different purposes (audit vs migration)
• Delete unused tokens once migration is verified
• Store securely in password managers or secure credential storage
• Secure or remove any token files like bitbucket_api_token.txt

Token Permissions Matrix

Operation	Bitbucket Token	GitHub PAT	GitHub CLI
Repository audit	Read access	Not needed	Not needed
Issue migration	Read access	Repo access	Not needed
PR migration	Read access	Repo access	Not needed
Attachment upload	Read access	Repo access	Authenticated

---

✅ Authentication Testing

Test Bitbucket Authentication

Use the provided test script to verify your Bitbucket token:

migrate_bitbucket_to_github test-auth --workspace YOUR_WORKSPACE --repo YOUR_REPO --email you@example.com --token ATAT1234...

Expected output:

✅ All tests passed! Your API Token is working correctly.

If tests fail: The script provides detailed troubleshooting guidance and token creation instructions.

Test GitHub Authentication

Verify your GitHub PAT works correctly:

# Test basic authentication
curl -H "Authorization: token ghp_abcd123..." https://api.github.com/user

# Test repository access
curl -H "Authorization: token ghp_abcd123..." https://api.github.com/repos/YOUR_ORG/YOUR_REPO

# Test issue creation (dry run)
curl -X POST -H "Authorization: token ghp_abcd123..." \
  https://api.github.com/repos/YOUR_ORG/YOUR_REPO/issues \
  -d '{"title":"Test Issue","body":"Testing authentication"}'

Test GitHub CLI Authentication

# Check authentication status
gh auth status

# Test repository access
gh repo view YOUR_ORG/YOUR_REPO

# Test issue creation (dry run)
gh issue create --title "Test Issue" --body "Testing CLI auth" --repo YOUR_ORG/YOUR_REPO

---

🔍 Troubleshooting Authentication Issues

Bitbucket Token Problems

"401 Unauthorized"

• Verify token is correct (copy-paste errors are common)
• Check if token has expired
• Ensure you're using a user-level API token (not Repository Access Token)
• Confirm token has issue and PR read permissions

"403 Forbidden"

• Token may lack required permissions
• Repository may be private and token doesn't have access
• Workspace access may be restricted

"404 Not Found"

• Verify workspace and repository names are correct
• Check if repository exists and is accessible

GitHub Token Problems

"401 Unauthorized"

• Verify PAT is correct and not expired
• Check if PAT has repo scope enabled
• Ensure you're using a classic token (not fine-grained)

"403 Forbidden"

• PAT may lack required scopes
• Repository may be private and PAT doesn't have access
• Organization may require PAT approval

"404 Not Found"

• Verify repository exists and is accessible
• Check if organization/repository names are correct

GitHub CLI Problems

"gh: Not logged in"

gh auth login

"Repository not found"

• Verify repository exists
• Check if CLI is authenticated to correct GitHub account
• Ensure repository is accessible with current authentication

"Permission denied"

• CLI may be authenticated to different account than PAT
• Repository may require different access level
• Organization may restrict CLI access

Integration Issues

"GitHub CLI not available" (when using --use-gh-cli)

• Install GitHub CLI: https://cli.github.com/
• Verify installation: gh --version
• Authenticate: gh auth login

"Authentication mismatch"

• Ensure GitHub PAT and CLI are authenticated to same account
• Check if you're a member of the target organization
• Verify repository access permissions

---

💡 Verification Workflow

Before Running Audit Script

1. Set environment variables:

   export BITBUCKET_TOKEN="ATAT1234..."
   

2. Test Bitbucket authentication:

   migrate_bitbucket_to_github test-auth --workspace YOUR_WORKSPACE --repo YOUR_REPO --email you@example.com
   

3. Verify repository access:

   curl -u you@example.com:$BITBUCKET_TOKEN https://api.bitbucket.org/2.0/repositories/YOUR_WORKSPACE/YOUR_REPO
   

4. Run audit script:

   migrate_bitbucket_to_github audit --workspace YOUR_WORKSPACE --repo YOUR_REPO --email you@example.com
   

Before Running Migration Script

1. Set environment variables:

   export GITHUB_TOKEN="ghp_123..."
   

2. Test GitHub PAT:

   curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user
   

3. Test repository access:

   curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/repos/YOUR_ORG/YOUR_REPO
   

4. Test GitHub CLI (if using --use-gh-cli):

   gh auth status
   gh repo view YOUR_ORG/YOUR_REPO
   

5. Run dry-run migration:

   migrate_bitbucket_to_github dry-run --config config.json
   

After Authentication Issues

1. Check token scopes and permissions
2. Verify repository access
3. Test with minimal operations first
4. Use dry-run modes to validate setup
5. Check the troubleshooting guides above

---

🚀 Quick Start Commands

Basic Setup (No Attachments)

# 1. Set environment variables
export BITBUCKET_TOKEN="ATAT123..."
export GITHUB_TOKEN="ghp_456..."

# 2. Test Bitbucket token
migrate_bitbucket_to_github test-auth --workspace myteam --repo myrepo --email me@company.com

# 3. Run audit
migrate_bitbucket_to_github audit --workspace myteam --repo myrepo --email me@company.com

# 4. Test GitHub PAT
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user

# 5. Run migration dry-run
migrate_bitbucket_to_github dry-run --config config.json

Advanced Setup (With Auto-Upload)

# 1. Install and setup GitHub CLI
gh auth login

# 2. Test CLI authentication
gh auth status

# 3. Run migration with auto-upload
migrate_bitbucket_to_github migrate --config config.json --use-gh-cli

---

📋 Token Requirements Summary

Feature	Bitbucket Token	GitHub PAT	GitHub CLI
Repository audit	✅ User-level, read access	❌	❌
Issue migration	✅ User-level, read access	✅ repo scope	❌
PR migration	✅ User-level, read access	✅ repo scope	❌
Attachment upload	✅ User-level, read access	✅ repo scope	✅ Authenticated
User mapping	✅ User-level, read access	✅ repo, user:email	❌

Key Points:

• Always use user-level Bitbucket API tokens (not Repository Access Tokens)
• GitHub PAT requires repo scope for full functionality
• GitHub CLI is only needed for automatic attachment uploads
• Test authentication before running migration scripts
• Use dry-run modes to validate your setup