Bitbucket サーバーから GitHub Enterprise クラウドへの移行の概要

計画から実装、フォローアップ タスクの完了まで、Bitbucket Server から GitHub Enterprise Importer を備えた GitHub への移行プロセスについて説明します。

この記事の内容

概要

GitHub Enterprise Importer を使用すると、リポジトリごとに GitHub Enterprise Cloud に移行できます。 詳しくは、「GitHub Enterprise Importer について」を参照してください。

Bitbucket Server から移行する場合、このガイドを使用して移行を計画および実装し、フォローアップ タスクを完了できます。

移行を計画する

移行を計画するには、次の質問に対する答えを考えてください。

どのくらいで移行を完了する必要があるか?

タイムラインを決定します。これによって、アプローチが大きく異なります。 タイムラインを決定するための最初の手順は、移行する必要があるもののインベントリを取得することです。

  • リポジトリの数
  • pull request の数

移行の所要時間は、主にリポジトリ内の pull request の数に基づきます。 1,000 個のリポジトリを移行する必要があり、各リポジトリには平均で 100 個の pull request があり、リポジトリに貢献したユーザーが 50 人しかいない場合、移行は非常に迅速に完了する可能性があります。 移行する必要があるリポジトリは 100 個であるが、各リポジトリに平均で 75,000 個の pull request があり、5,000 人のユーザーがいる場合、移行にかかる時間ははるかに長くなり、必要な計画とテストもはるかに多くなります。

移行する必要があるリポジトリのインベントリを取得したら、インベントリ データと目的のタイムラインを比較検討します。 組織がより高度な変更に耐えられる場合、すべてのリポジトリを一度に移行して、移行作業を数日で完了できる可能性があります。 しかし、さまざまなチームがあり、それらを同時に移行できない場合もあります。 このような場合、チームのタイムラインに合わせて移行をバッチ処理し、移行が重ならないように調整できますが、移行作業の期間は長くなります。

  1. 移行する必要があるリポジトリと pull request の数を決定します。
  2. チームの移行の準備が整うタイミングを把握するには、関係者にインタビューします。
  3. このガイドの残りの部分を完全に確認してから、移行のタイムラインを決定してください。

何が移行されるかを理解しているか?

GitHub Enterprise Importer によって移行できるデータを自分と関係者が理解していることを確認します。

Bitbucket Server からの移行の場合、GitHub Enterprise Importer では Git リポジトリと pull request のみが移行されます。 CI パイプラインなどのその他の資産は、Bitbucket Server に残ります。

GitHub と Bitbucket Server ではアクセス許可の動作が異なるため、GitHub Enterprise Importer は Bitbucket Server からリポジトリのアクセス許可を移行しようとはしません。 詳しくは、「アクセス許可の構成」を参照してください。

  1. Bitbucket Server から移行されたデータを確認します。 詳しくは、「Bitbucket サーバーから GitHub Enterprise クラウドへの移行について」を参照してください。
  2. 手動で移行または再作成する必要があるデータの一覧を作成します。

誰が移行を実行するか?

リポジトリを移行するには、GitHub 内の移行先の Organization の Organization 所有者であるか、Organization 所有者が移行者ロールを付与する必要があります。

また、Bitbucket Server インスタンスに必要なアクセス許可とアクセス権も必要です。

  • 管理者またはスーパー管理者のアクセス許可
  • Bitbucket Server インスタンスで Linux が実行されている場合、サポートされている秘密キーを使用してインスタンスへの SFTP アクセス (「Bitbucket サーバーからの移行のアクセスの管理」を参照)
  • Bitbucket Server インスタンスで Windows が実行されている場合、そのインスタンスへのファイル共有 (SMB) アクセス
  1. 移行先の Organization の Organization 所有者に移行を実行させるか、移行者ロールを他のユーザーに付与する必要があるかを決定します。
  2. 移行者ロールを付与する場合は、ロールを付与する個人またはチームを決めます。
  3. 移行者ロールを個人またはチームに付与します。 詳しくは、「Bitbucket サーバーからの移行のアクセスの管理」をご覧ください。
  4. ユーザーが、すべてのアクセス要件を満たすように personal access token を正しく構成していることを確認します。詳しくは、「Bitbucket サーバーからの移行のアクセスの管理」をご覧ください。
  5. 移行者に、Bitbucket Server インスタンスの管理者またはスーパー管理者のアクセス許可と SFTP アクセス権があることを確認します。

GitHub ではどんな Organization 構造が必要か?

次に、GitHub で作成する Organization 構造を計画します。

Bitbucket Server では、リポジトリはプロジェクトにグループ化されます。 GitHub では、リポジトリは Organization によって所有されます。 ただし、Bitbucket Server のプロジェクトごとに GitHub に 1 つの Organization を作成することが最善の方法であるとは考えないでください。

GitHub に移行した後は、Enterprise アカウントを 1 つのみにし、その Enterprise で所有する Organization の数を少なくする必要があります。

移行された各リポジトリは、これらの Organization の 1 つによって所有されるため、各組織内でグループ化されていないリポジトリのリストが大きくなる可能性があります。 ただし、GitHub でチームを作成することで、リポジトリのグループへのアクセスを管理できます。 詳しくは、「Team について」を参照してください。

移行作業をバッチ処理に分割する場合、Organization 別のバッチ処理を検討します。

  1. 新しい Organization の構造を決めます。
  2. 移行作業を小さいバッチに分割する必要があるかどうかを決めます。
  3. そうする場合は、移行の分割方法を決めます。

移行の実行

計画が完了したら、実際の移行を開始できます。 自分の Enterprise に固有の、移行中および移行後の問題を明らかにするため、すべての移行の試験的実行を行うことを強くお勧めします。 試験的実行で明らかになった問題を解決した後、運用環境の移行を実行できます。

試験的移行は、いくつかの重要な情報を特定するのに役立ちます。

  • 特定のリポジトリの移行を正常に完了できるかどうか
  • ユーザーが正常に作業を開始できる状態に、リポジトリを戻すことができるかどうか
  • 移行の実行にかかる時間。これは、移行のスケジュールを計画し、利害関係者の期待を設定するのに役立ちます

試験的実行に多くの時間をかける必要はありません。 GitHub Enterprise Importer では、移行対象のリポジトリのユーザーにダウンタイムは必要ありません。 ただし、運用環境の移行の間は、移行中に新しいデータが作成されないようにするため、作業を停止することをお勧めします。作成されたものは、移行されたリポジトリに含まれません。 試験的移行にはこのような問題はないので、試験的実行はいつでも行うことができます。 試験的移行の完了にかかる時間を短縮するには、試験的実行のバッチを連続してスケジュールできます。 それらのリポジトリのユーザーは、都合のよいときに結果を検証できます。

試用版の移行の移行先として使用するテスト用 Organization を作成することをお勧めします。 すべての試験的実行に 1 つの Organization を使うことも、目的の移行先 Organization ごとに 1 つのテスト Organization を作成することもできます。 Organization が移行検証のみを目的としており、運用環境向けではないことを明確にするために、Organization 名の末尾に -sandbox を含めることを検討してください。 終わったら、テスト Organization を削除してかまいません。

  1. 試用版の移行のテスト用 Organization を作成します。
  2. 試験的移行を実行します。
  3. 試験的移行では、以下で説明するフォローアップ タスクを完了します。
  4. 移行の結果を検証するようにユーザーに依頼します。
  5. 試験的移行によって明らかになった問題を解決します。
  6. 移行先で IP 許可リストを使っている場合は、GitHub Enterprise Importer によるアクセスを許可するようにリストを構成します。詳しくは、「Bitbucket サーバーからの移行のアクセスの管理」を参照してください。
  7. 運用移行を実行します。 詳しくは、「Bitbucket Server から GitHub Enterprise Cloud へのリポジトリの移行」を参照してください。
  8. 必要に応じて、テスト用の Organization を削除します。

フォローアップ タスクの完了

各移行が完了したら、リポジトリが機能する状態になる前に、いくつかの追加タスクを完了する必要があります。

移行の状態を確認する

まず、移行が成功したか失敗したかをチェックします。

移行の状態をチェックする方法は、移行の実行方法によって異なります。

  • GitHub CLI を使用して移行を実行した場合、既定では、移行が完了すると移行が成功したか失敗したかがプロセスにより表示されます。 移行が失敗した場合は、失敗の理由が表示されます。

    Migration completed (ID: RM_123)! State: SUCCEEDED

  • オプションの --queue-only 引数を使用して GitHub CLI により移行を実行した場合、プロセスは移行がキューに登録されるとすぐに終了し、移行が成功したか失敗したかは通知されません。 wait-for-migration コマンドを使用するか、移行ログを確認して、移行の状態をチェックできます。

  • GraphQL API を使用して移行を実行した場合は、RepositoryMigration オブジェクトの state フィールドと failureReason フィールドのクエリを実行できます。

移行が失敗した場合、移行ログに失敗の原因に関する追加情報がある可能性があります。 詳細については、「移行ログの確認」を参照してください。

移行ログの確認

移行された各リポジトリの移行ログを確認します。 詳しくは、「GitHub Enterprise Importer の移行ログへのアクセス」を参照してください。

移行が失敗した場合、ログに失敗の原因に関する追加情報がある可能性があります。

移行が成功した場合、移行されていないまたは警告付きで移行された特定のデータの部分 (pull request、イシュー、コメントなど) を表す警告が移行ログに含まれている場合があります。

移行の警告の詳細については、「GitHub Enterprise Importer を使用した移行のトラブルシューティング」を参照してください。 移行の警告を確認したら、それらの警告を受け入れて先に進むことができるかどうかを決定する必要があります。

リポジトリの可視性を設定する

すべてのリポジトリは、既定ではプライベートとして移行され、移行を実行したユーザーと組織の所有者のみが、リポジトリにアクセスできます。 リポジトリをプライベートにしたくない場合は、可視性を変更します。

  • --target-repo-visibility CLI オプションまたは targetRepoVisibility GraphQL プロパティを使用して、リポジトリの表示範囲を設定できます。
  • リポジトリの可視性はブラウザーで変更できます。 詳しくは、「リポジトリの可視性を設定する」を参照してください。
  • または、GitHub CLI を使って、コマンド ラインからリポジトリの可視性を変更することもできます。 移行を実行するために生成されたスクリプトに、このコマンドを追加することもできます。 詳細については、GitHub CLI ドキュメントの「gh repo edit」を参照してください。

Configuring permissions

GitHub と Bitbucket Server ではアクセス許可の動作が異なるため、GitHub Enterprise Importer は Bitbucket Server からリポジトリのアクセス許可を移行しようとはしません。

移行されたリポジトリへのアクセス権を付与するには、チームを作成し、各チームにリポジトリへのアクセス権を付与します。

  1. チームを作成します。 詳しくは、「Team の作成」を参照してください。
  2. Organization メンバーをチームに追加します。 詳しくは、「Team への Organization メンバーの追加」を参照してください。
  3. 各チームにリポジトリへのアクセス権を付与します。 詳しくは、「Organization のリポジトリに対するチームのアクセスを管理する」を参照してください。

マネキンの回収

GitHub Enterprise Importer を使って移行を実行した後、移行されたリポジトリでのすべてのユーザー アクティビティ (Git コミットを除く) は、マネキンと呼ばれるプレースホルダー ID に帰属します。

GitHub CLI またはブラウザーを使用して、各マネキンの履歴を組織のメンバーにもう一度帰属させることができます。 GitHub CLI を使う場合は、マネキンを一括して回収できます。詳しくは、「GitHub Enterprise Importer のマネキンの回収」をご覧ください。

注: マネキンを回収できるのは Organization の所有者だけです。 移行者ロールが付与されているユーザーは、Organization 所有者にこのステップの実行を依頼してください。

  1. マネキンを回収するかどうかを決めます。
  2. いつ回収を完了するかを計画します。
  3. マネキンを回収します。
  4. チーム メンバーシップを介してリポジトリへの適切なアクセス権をまだ持っていないメンバーがいる場合は、そのメンバーにリポジトリへのアクセス権を付与します。 詳しくは、「Organization のリポジトリへの個人のアクセスを管理する」を参照してください。

IP 許可リストの構成

GitHub Enterprise Importer の IP 範囲を移行先の Organization の IP 許可リストに追加した場合、それらのエントリを削除できます。 移行先 Enterprise に対する ID プロバイダーの IP 許可リスト制限を無効にした場合は、ここでもう一度有効にできます。

詳しくは、「Bitbucket サーバーからの移行のアクセスの管理」を参照してください。