Bitbucket Server から GitHub Enterprise Cloud へのリポジトリの移行

GitHub CLI を使用して、Bitbucket Server から GitHub Enterprise Cloud にリポジトリを移行することができます。

この記事の内容

GitHub Enterprise Importer

を使ったリポジトリの移行について

GitHub CLI を使用して、BitBucket Server インスタンスから個々のリポジトリまたはすべてのリポジトリを移行できます。

現時点では、GitHub API を使用した Bitbucket Server からの移行はサポートされていません。

Note

移行しているリポジトリに、受信リポジトリが一致しないルールセットがある場合、この移行はブロックされます。 これらのルールセットをバイパスして移行を許可するには、ターゲット組織のすべてのデプロイ キーにルールセット バイパスを適用します。

リポジトリのルールセットは、組織レベルで設定できます。 受信リポジトリがこれらのルールセットのいずれにも一致しない場合は、それぞれにデプロイ キーバイパスを使用する必要があります。 「組織内のリポジトリのルールセットを作成する」をご覧ください。

前提条件

  • 移行の試験的実行を行い、そのすぐ後で運用環境の移行を完了することを強くお勧めします。 試験的実行について詳しくは、「Bitbucket サーバーから GitHub Enterprise クラウドへの移行の概要」をご覧ください。
  • 移行されるデータと、Importer の既知のサポート制限事項を理解していることを確認します。 詳しくは、「Bitbucket サーバーから GitHub Enterprise クラウドへの移行について」をご覧ください。
  • 必須ではありませんが、運用環境の移行の間は作業を停止することをお勧めします。 Importer は差分移行をサポートしていないため、移行中に発生した変更は移行されません。 運用環境の移行の間に作業を停止しない場合は、これらの変更を手動で移行する必要があります。
  • GitHub.com の移行先の Organization では、Organization 所有者であるか、移行者ロールを持っている必要があります。 詳しくは、「Bitbucket サーバーからの移行のアクセスの管理」を参照してください。
  • 管理者またはスーパー管理者のアクセス許可がある Bitbucket Server アカウントのユーザー名とパスワードが必要です。

手順 1: BBS2GH extension of the GitHub CLI をインストールする

これが初めての移行の場合は、BBS2GH extension of the GitHub CLI をインストールする必要があります。 GitHub CLI について詳しくは、「GitHub CLI について」をご覧ください。

または、github/gh-bbs2gh リポジトリの「リリース ページ」からスタンドアロン バイナリをダウンロードすることもできます。 このバイナリは、gh プレフィックスなしで直接実行できます。

  1. GitHub CLI をインストールします。 GitHub CLI のインストール手順については、GitHub CLI リポジトリを参照してください。

    注: GitHub CLI のバージョン 2.4.0 以降が必要です。 gh --version コマンドを使って、インストールされているバージョンを確認できます。

  2. BBS2GH extension をインストールします。

    Shell
    gh extension install github/gh-bbs2gh

BBS2GH extension に関するヘルプが必要なときはいつでも、コマンドで --help フラグを使用できます。 たとえば、gh bbs2gh --help とすると使用可能なすべてのコマンドの一覧が表示され、gh bbs2gh migrate-repo --help とすると migrate-repo コマンドで使用できるすべてのオプションの一覧が表示されます。

手順 2: BBS2GH extension of the GitHub CLI を更新する

BBS2GH extension of the GitHub CLI は毎週更新されます。 最新バージョンを確実に使うため、拡張機能を更新してください。

Shell
gh extension upgrade github/gh-bbs2gh

手順 3: 環境変数を設定する

BBS2GH extension を使って GitHub Enterprise Cloud に移行するには、その前に、移行先の Organization にアクセスできる personal access token を作成してから、personal access token を環境変数として設定する必要があります。

また、Bitbucket Server のユーザー名とパスワードの環境変数を設定し、Bitbucket Server インスタンスが Windows で実行されている場合は SMB パスワードを設定する必要があります。

  1. GitHub Enterprise Cloud 上の移行先 Organization に対して認証を行う personal access token (classic) を作成して記録し、トークンがすべての要件を満たしていることを確認します。 詳しくは、「Bitbucket サーバーからの移行のアクセスの管理」を参照してください。

  2. 環境変数を設定し、TOKEN は先ほど記録した personal access token、USERNAME は管理者またはスーパー管理者のアクセス許可を持つ Bitbucket Server アカウントのユーザー名、PASSWORD は Bitbucket Server アカウントのパスワードに置き換えます。

    • ターミナルを使っている場合は、export コマンドを使います。

      Shell
      export GH_PAT="TOKEN"
export BBS_USERNAME="USERNAME"
export BBS_PASSWORD="PASSWORD"
# If your Bitbucket Server instance runs on Windows
export SMB_PASSWORD="PASSWORD"

    • PowerShell を使っている場合は、$env コマンドを使います。

      Shell
      $env:GH_PAT="TOKEN"
$env:BBS_USERNAME="USERNAME"
$env:BBS_PASSWORD="PASSWORD"
# If your Bitbucket Server instance runs on Windows
$env:SMB_PASSWORD="PASSWORD"

手順 4: BLOB ストレージを設定する

多くの Bitbucket Server インスタンスはファイアウォールの背後にあるため、GitHub CLI では、インターネットから到達可能なデータを格納するための中間的な場所として BLOB ストレージが使用されます。

最初に、移行するデータのアーカイブを生成し、ファイアウォールの背後から BLOB ストレージにデータをプッシュします。

GitHub CLI は、次の BLOB ストレージ プロバイダーをサポートしています。

  • アマゾン ウェブ サービス (AWS) S3
  • Azure Blob Storage

移行を実行する前に、選んだクラウド プロバイダーでストレージ コンテナーを設定してデータを格納する必要があります。

AWS S3 ストレージ バケットの設定

AWS で、S3 バケットを設定します。 詳しくは、AWS のドキュメント「バケットの作成」をご覧ください。

次のアクセス許可を持つ AWS アクセス キーと秘密鍵も必要です。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:ListBucketMultipartUploads",
                "s3:AbortMultipartUpload",
                "s3:ListBucket",
                "s3:DeleteObject",
                "s3:ListMultipartUploadParts"
            ],
            "Resource": [
                "arn:aws:s3:::github-migration-bucket",
                "arn:aws:s3:::github-migration-bucket/*"
            ]
        }
    ]
}

注: GitHub Enterprise Importer は、移行の完了後に AWS からアーカイブを削除しません。 ストレージ コストを減らすため、一定期間後にアーカイブが自動削除されるよう構成することをお勧めします。 詳しくは、AWS のドキュメントの「バケットのライフサイクル設定の指定」をご覧ください。

移行を実行する準備ができたら、リージョン、アクセス キー、シークレット キー、セッション トークンなどの AWS 資格情報を GitHub CLI に提供します (必要な場合)。 引数として渡すことも、AWS_REGION、AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKEN という環境変数を設定することもできます。

また、--aws-bucket-name 引数を使って S3 バケットの名前で渡す必要があります。

Azure Blob Storage ストレージ アカウントの設定

Azure でストレージ アカウントを作成し、接続文字列を記録しておきます。 詳しくは、Microsoft Docs の「ストレージ アカウント アクセス キーを管理する」をご覧ください。

注: GitHub Enterprise Importer は、移行の完了後に Azure Blob Storage からアーカイブを削除しません。 ストレージ コストを減らすため、一定期間後にアーカイブが自動削除されるよう構成することをお勧めします。 詳しくは、Microsoft Docs の「データ ライフサイクルを自動管理してコストを最適化する」をご覧ください。

移行を実行する準備ができたら、接続文字列を引数として GitHub CLI に渡すか、AZURE_STORAGE_CONNECTION_STRING という名前の環境変数を使って渡すことができます。

手順 5: リポジトリを移行する

gh bbs2gh migrate-repo コマンドを使ってリポジトリを移行できます。

既定では、リポジトリを移行するときに、BBS2GH extension of the GitHub CLI によって次の手順が行われます。

  1. Bitbucket Server インスタンスに接続し、リポジトリごとに移行アーカイブを生成します
  2. SFTP (Linux) または SMB (Windows) を使用して、移行アーカイブを Bitbucket Server インスタンスから BBS2GH extension of the GitHub CLI を実行しているコンピューターにダウンロードします
  3. 移行アーカイブを任意の BLOB ストレージ プロバイダーにアップロードします
  4. BLOB ストレージ プロバイダーに格納されているアーカイブの URL を使用して、GitHub Enterprise Cloud で移行を開始します
  5. ローカル コンピューターから移行アーカイブを削除します。 (移行が完了したら、BLOB ストレージ プロバイダーからアーカイブを手動で削除する必要があります。)

または、GitHub CLI を使ってアーカイブを生成し、そのアーカイブを手動でダウンロードしてから、GitHub CLI を使って移行を続けることもできます。

移行アーカイブをダウンロードすることを GitHub CLI に許可する

1 つのリポジトリを移行するには、gh bbs2gh migrate-repo コマンドを使います。

以下のようにアクセスできるコンピューターからこの手順に従う必要があります。

  • HTTPS 経由で Bitbucket Server インスタンス
  • Bitbucket Server インスタンスが Linux 上で実行されている場合は、SFTP 経由で Bitbucket Server インスタンス。 一般に、SSH 経由でサーバーにアクセスできる場合は、SFTP を使用することもできます。
  • Bitbucket Server インスタンスが Windows で実行されている場合は、SMB 経由で Bitbucket Server インスタンス
  • 選んだ BLOB ストレージ プロバイダー
Shell
gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT --bbs-repo CURRENT-NAME \
  --github-org DESTINATION --github-repo NEW-NAME \
  # Use the following options if your Bitbucket Server instance runs on Linux
  --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
  # Use the following options if your Bitbucket Server instance runs on Windows
  --smb-user SMB-USER
  # Use the following option if you're using AWS S3 as your blob storage provider
  --aws-bucket-name AWS-BUCKET-NAME
  # Use the following option if you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer
  --archive-download-host ARCHIVE-DOWNLOAD-HOST

上のコマンドのプレースホルダーを次の値に置き換えます。

プレースホルダー値
BBS-SERVER-URLBitbucket Server インスタンスの URL
PROJECT移行するリポジトリの Bitbucket Server プロジェクト用のキー
CURRENT-NAME移行するリポジトリの名前
DESTINATION移行先の Organization の名前
NEW-NAME移行されたリポジトリに設定する名前
SSH-USERBitbucket Server インスタンスが Linux 上で実行されている場合、SFTP 経由で Bitbucket Server に接続するときに使うユーザー名
PATH-TO-KEYBitbucket Server インスタンスが Linux 上で実行する場合は、SSH 秘密キーへのパス (例: ~/.ssh/id_rsa)。 SSH キーの要件については、「Bitbucket サーバーからの移行のアクセスの管理」をご覧ください。
SMB-USERBitbucket Server インスタンスが Windows 上で実行されている場合、SMB 経由で Bitbucket Server に接続するときに使うユーザー名
AWS-BUCKET-NAMEAWS S3 バケットのバケット名
ARCHIVE-DOWNLOAD-HOSTSSH または SMB 経由で Bitbucket サーバー/データ センターのインスタンスに接続するために使うホスト。 これを指定する必要があるのは、Bitbucket Data Center クラスターを使っている場合、または Bitbucket サーバーがロード バランサーの背後にある場合のみです。

注: Renci.SshNet を示すエラーが発生した場合、CLI では、移行アーカイブをダウンロードするためにサーバーへの SFTP 接続を確立する際に Issue が発生しています。 これらの Issue をトラブルシューティングする方法については、「GitHub Enterprise Importer を使用した移行のトラブルシューティング」を参照してください。

移行アーカイブを手動でダウンロードする

BBS2GH extension of the GitHub CLI の既定では、SFTP または SMB を使って Bitbucket Server インスタンスからの移行アーカイブのダウンロードを含め、移行全体が実行されます。

ただし、サーバーが SFTP アクセスを提供していない場合など、移行アーカイブを手動でダウンロードすることを好むお客様もいます。 その場合は、GitHub CLI を使ってアーカイブを生成し、そのアーカイブを手動でダウンロードしてから、GitHub CLI を使って移行を続けることもできます。

以下のようにアクセスできるコンピューターからこの手順に従う必要があります。

  • HTTPS 経由で Bitbucket Server インスタンス
  • 選んだ BLOB ストレージ プロバイダー

まず、次の引数のみを指定して gh bbs2gh migrate-repo コマンドを実行します。

Shell
gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT \
  --bbs-repo CURRENT-NAME

上のコマンドのプレースホルダーを次の値に置き換えます。

プレースホルダー値
BBS-SERVER-URLBitbucket Server インスタンスの URL
PROJECT移行するリポジトリの Bitbucket Server プロジェクト用のキー
CURRENT-NAME移行するリポジトリの名前

移行アーカイブが生成され、コマンド出力にパスが出力されます。

[12:14] [INFO] Export completed. Your migration archive should be ready on your
instance at $BITBUCKET_SHARED_HOME/data/migration/export/Bitbucket_export_9.tar

一般に、$BITBUCKET_SHARED_HOME は Linux では /var/atlassian/application-data/bitbucket/shared、Windows では C:\Atlassian\ApplicationData\Bitbucket\Shared に設定されますが、サーバーの構成によって異なる場合があります。 共有ホーム ディレクトリを特定する方法については、「GitHub Enterprise Importer を使用した移行のトラブルシューティング」を参照してください。

Bitbucket Server インスタンスから移行アーカイブをダウンロードし、GitHub CLI を実行しているマシンにアーカイブを格納します。

移行アーカイブを GitHub にインポートするには、別の引数セットを指定して gh bbs2gh migrate-repo コマンドをもう一度実行します。

Shell
gh bbs2gh migrate-repo --archive-path ARCHIVE-PATH \
  --github-org DESTINATION --github-repo NEW-NAME \
  --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT \
  --bbs-repo CURRENT-NAME \
  # Use the following option if you're using AWS S3 as your blob storage provider
  --aws-bucket-name AWS-BUCKET-NAME

上のコマンドのプレースホルダーを次の値に置き換えます。

プレースホルダー値
ARCHIVE-PATHお使いのインスタンスからダウンロードした Bitbucket Server 移行アーカイブのパス
DESTINATION移行先の Organization の名前
NEW-NAME移行されたリポジトリに設定する名前
BBS-SERVER-URLBitbucket Server インスタンスの URL
PROJECT移行するリポジトリの Bitbucket Server プロジェクト用のキー
CURRENT-NAME移行するリポジトリの名前
AWS-BUCKET-NAMEAWS S3 バケットのバケット名

移行を取り消す

移行を取り消す場合は、MIGRATION-ID を abort-migration 返された（ migrate-repoから）ID に置き換えて、コマンドを使用します。

Shell
gh bb2gh abort-migration --migration-id MIGRATION-ID

手順 6: 移行を検証し、エラー ログを確認する

移行が完了したら、移行ログを確認することをお勧めします。 詳しくは、「GitHub Enterprise Importer の移行ログへのアクセス」を参照してください。

移行したリポジトリで健全性チェックを確認することをお勧めします。

手順 7: 複数のリポジトリを移行する

複数のリポジトリを GitHub Enterprise Cloud に一度に移行したい場合は、GitHub CLI を使って移行スクリプトを生成します。 結果のスクリプトには、リポジトリごとに 1 つの移行コマンドのリストが含まれます。

注: スクリプトを生成すると、PowerShell スクリプトが出力されます。 ターミナルを使っている場合は、.ps1 ファイル拡張子を持つスクリプトを出力し、Mac または Linux 用の PowerShell をインストールして実行する必要があります。

移行スクリプトの生成

HTTPS 経由で Bitbucket Server インスタンスにアクセスできるコンピューターからこの手順に従う必要があります。

移行スクリプトを生成するには、gh bbs2gh generate-script コマンドを実行します。

Shell
gh bbs2gh generate-script --bbs-server-url BBS-SERVER-URL \
  --github-org DESTINATION \
  --output FILENAME \
  # Use the following options if your Bitbucket Server instance runs on Linux
  --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
  # Use the following options if your Bitbucket Server instance runs on Windows
  --smb-user SMB-USER
  # Use the following option if you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer
  --archive-download-host ARCHIVE-DOWNLOAD-HOST

移行された各リポジトリの移行ログをダウンロードするスクリプトが必要な場合は、--download-migration-logs フラグを追加します。 移行ログについて詳しくは、「GitHub Enterprise Importer の移行ログへのアクセス」をご覧ください。

上のコマンドのプレースホルダーを次の値に置き換えます。

プレースホルダー値
BBS-SERVER-URLBitbucket Server インスタンスの URL
DESTINATION移行先の Organization の名前
FILENAME結果の移行スクリプトのファイル名

ターミナルを使っている場合は、生成されたスクリプトの実行に PowerShell が必要なので、.ps1 ファイル拡張子を使います。 Mac 用または Linux 用の PowerShell をインストールできます。
SSH-USERBitbucket Server インスタンスが Linux 上で実行されている場合、SFTP 経由で Bitbucket Server に接続するときに使うユーザー名
PATH-TO-KEYBitbucket Server インスタンスが Linux 上で実行する場合は、SSH 秘密キーへのパス (例: ~/.ssh/id_rsa)。 SSH キーの要件については、「Bitbucket サーバーからの移行のアクセスの管理」をご覧ください。
SMB-USERBitbucket Server インスタンスが Windows 上で実行されている場合、SMB 経由で Bitbucket Server に接続するときに使うユーザー名
ARCHIVE-DOWNLOAD-HOSTSSH または SMB 経由で Bitbucket サーバー/データ センターのインスタンスに接続するために使うホスト。 これを指定する必要があるのは、Bitbucket Data Center クラスターを使っている場合、または Bitbucket サーバーがロード バランサーの背後にある場合のみです。

移行スクリプトの確認

スクリプトを生成したら、ファイルを確認し、必要に応じてスクリプトを編集します。

  • 移行したくないリポジトリがある場合は、対応する行を削除するかコメントにします。
  • 既定では、GitHub のリポジトリ名は projectKey-repositoryName 規則に従います。 たとえば、キー OS を持つ open-source プロジェクトの一部である airports という名前の Bitbucket Server リポジトリは、GitHub では OS-airports と呼ばれます。 GitHub でリポジトリに別の名前を使う場合は、対応する --github-repo フラグの値を更新します。

BBS2GH を GitHub CLI の拡張機能としてではなくスタンドアロン バイナリとしてダウンロードした場合は、生成されたスクリプトを更新して、gh bbs2gh ではなくバイナリを実行する必要があります。

移行スクリプトの実行

リポジトリを移行するには、生成されたスクリプトを実行します。

以下のようにアクセスできるコンピューターからこの手順に従う必要があります。

  • HTTPS 経由で Bitbucket Server インスタンス
  • Bitbucket Server インスタンスが Linux 上で実行されている場合は、SFTP 経由で Bitbucket Server インスタンス。 一般に、SSH 経由でサーバーにアクセスできる場合は、SFTP を使用することもできます。
  • Bitbucket Server インスタンスが Windows で実行されている場合は、SMB 経由で Bitbucket Server インスタンス
  • 選んだ BLOB ストレージ プロバイダー

スクリプトを実行する前に、BLOB ストレージ プロバイダーに対する認証を行うために追加の環境変数を設定する必要があります。

  • AWS S3 の場合は、次の環境変数を設定します。
    • AWS_ACCESS_KEY_ID: バケットのアクセス キー ID
    • AWS_SECRET_ACCESS_KEY: バケットの秘密鍵
    • AWS_REGION: バケットが配置されている AWS リージョン
    • AWS_SESSION_TOKEN: AWS の一時的な資格情報を使用している場合のセッション トークン (AWS ドキュメントの「AWS リソースで一時的な資格情報を使用する」を参照してください)
  • Azure Blob Storage の場合は、AZURE_STORAGE_CONNECTION_STRING を Azure ストレージ アカウントの接続文字列に設定します。

ストレージ アカウントのアクセス キーを使う接続文字列のみがサポートされています。 Shared Access Signature (SAS) を使う接続文字列はサポートされていません。 ストレージ アカウントのアクセス キーについて詳しくは、Azure のドキュメントの「ストレージ アカウント アクセス キーを管理する」をご覧ください。

複数のリポジトリを移行するには、上で生成したスクリプトを実行します。 次のコマンドの FILENAME を、スクリプトの生成時に指定したファイル名に置き換えます。

  • ターミナルを使っている場合は、./ を使います。

    Shell
    ./FILENAME

  • PowerShell を使っている場合は、.\ を使います。

    Shell
    .\FILENAME