移行について
GitHub 製品間 (GitHub Enterprise Server から GitHub Enterprise Cloud) で、または Bitbucket Server や GitLab などの別のコード ホスティング プラットフォームから GitHub に移行する場合、コード、コードの履歴、過去のすべての会話やコラボレーションなどの作業を移動したいことがあります。
このガイドでは、移行を計画して移行を成功させる方法について説明します。 移行の準備方法、データの移動に使うことができるツール、移動を成功させる方法について説明します。
移行の用語
このガイドを使って移行を計画する前に、次の重要な用語について学習してください。
| 期間 | 定義 |
|---|---|
| コード ホスティング プラットフォーム | GitHub Enterprise Cloud、GitHub Enterprise Server、Bitbucket Server、GitLab.com など、ソース コード リポジトリをホストし、共同作業に使うオンライン ツール。 |
| バージョン コントロール システム (VCS) | 変更を行うコンピューター上のソース コードの変更を追跡および管理するために使うツール。 たとえば、コード ホスティング プラットフォームとして GitHub または GitLab を使っている場合は、Git バージョン コントロール システムを使います。 コード ホスティング プラットフォームとして Azure DevOps を使っている場合は、基になるバージョン コントロール システムとして Git または Team Foundation バージョン管理 (TFVC) を使うことができます。 VCS をまったく使わない可能性もあります。 |
| 移行元 | 移行元の場所。 通常、これはコード ホスティング プラットフォームですが、独自のコンピューターまたは共有ネットワーク ドライブの場合もあります。 |
| 移行先 | 移行先の GitHub 製品。 |
| 移行パス | 移行元と移行先の組み合わせ ("Bitbucket Server から GitHub Enterprise Cloud へ" など)。 特定の移行パスについて、GitHub には、GitHub Enterprise Importer など、移行に役立つ専門ツールが用意されています。 |
移行スコープを定義する
移行を計画する前に、移行の対象とタイミングを把握する必要があります。
移行元と移行先を定義する
まず、データの移動元を決定します。 これは、常にではありませんが通常は、コード ホスティング プラットフォームです。
コード ホスティング プラットフォームは、GitHub.com や GitHub Enterprise Server などの GitHub 製品である場合もあれば、Bitbucket Server、GitLab、Azure DevOps などの別のコード ホスティング プラットフォームである場合もあります。 ビジネスの規模と複雑さに応じて、複数の異なるコード ホスティング プラットフォームを使っているかもしれません。
コード ホスティング プラットフォームをまったく使わない場合は、たとえば、共有ネットワーク ドライブにコードを保存しているかもしれません。
コードがどこに存在しても、そこが "移行元" です。
また、移行先の GitHub 製品、つまり "移行先" も把握する必要があります。 これには GitHub.com、GHE.com、または GitHub Enterprise Server が考えられます。
移行するリポジトリの基本のインベントリを作成する
移行元と移行先を特定したら、移行が必要なデータを確かめます。
移行元で移行が必要なすべてのリポジトリのリストを含めた移行インベントリを作成する必要があります。 スプレッドシートを使うことをお勧めします。 出発点として、リポジトリごとに次のデータを記録する必要があります。
- 名前
- 所有者: GitHub では、これは Organization になりますが、他のツールでは、別の種類の所有者が存在する場合があります
- URL
- 最終更新時のタイムスタンプ
- pull request の数 (または移行元の同等の数)
- issue の数 (または移行元の同等の数)
GitHub Enterprise Cloud または GitHub Enterprise Server から移行する場合は、GitHub CLI の gh-repo-stats 拡張機能を使ってこのデータを取得できます。 コマンドをいくつか実行するだけで、gh-repo-stats によって、移行元の API に接続され、推奨されるすべてのフィールドを含む CSV が作成されます。 詳しくは、mona-actions/gh-repo-stats リポジトリを参照してください。
注: gh-repo-stats はサードパーティ製のオープンソース ツールであり、GitHub サポートではサポートされません。 このツールについてヘルプが必要な場合は、そのリポジトリで issue を開いてください。
Azure DevOps から移行する場合は、ADO2GH extension of the GitHub CLI の inventory-report コマンドをお勧めします。 inventory-report コマンドは Azure DevOps API で接続され、上記で提案したフィールドの一部を含む非常にシンプルな CSV がビルドされます。 ADO2GH extension of the GitHub CLI のインストール方法の詳細については、「Azure DevOps から GitHub Enterprise Cloud へのリポジトリの移行」を参照してください。
Bitbucket サーバーまたは Bitbucket データ センターから移行する場合は、BBS2GH extension of the GitHub CLI の inventory-report コマンドをお勧めします。 この inventory-report コマンドでは、Bitbucket インスタンスの API を使用して単純な CSV を構築します。 BBS2GH extension of the GitHub CLI のインストール方法の詳細については、「Bitbucket Server から GitHub Enterprise Cloud へのリポジトリの移行」を参照してください。
その他の移行元については、移行インベントリをご自身で作成します。 移行元のレポート ツール (使用可能な場合) または API を使ってスプレッドシートを作成でき、インベントリを手動で作成することもできます。
移行インベントリにどの方法を選ぶにしても、従ったプロセスまたは実行したコマンドをメモしておきます。 移行の計画を続けると、インベントリの再実行が必要になる可能性は非常に高いです。
すべてのリポジトリのリストを取得したら、移行するリポジトリを決定できます。 1 つのオプションは、完全にすべてを移行することです。 しかし、移行はリポジトリを評価し、不要になったリポジトリを削除する絶好の機会です。 多くの企業には、何百、場合によっては何千もの未使用の不要なリポジトリがあり、それらをアーカイブすると、移行がはるかに簡単になります。
リポジトリのサイズを測定する
基本の移行インベントリが完成したら、リポジトリのサイズに関する情報を収集します。 リポジトリが大きい場合や、含まれる個々のファイルが 100 MB を超える場合は、移行に時間がかかり、リスクが増え、使用可能な移行ツールが制限される可能性があります。
Git をバージョン コントロール システムとして使っている場合、重要なのは現在リポジトリにある大規模ファイルだけではありません。リポジトリの履歴にある大規模ファイルも重要です。 たとえば、過去にリポジトリに 100 MB を超えるファイルがあった場合、ファイルのすべてのトレースを削除するように履歴を書き換えていない限り、そのファイルは Git 履歴に残ります。 履歴の書き換えについて詳しくは、「GitHub での大きいファイルについて」を参照してください。
gh-repo-stats を使ってインベントリを作成した場合は、リポジトリの大きさに関する基本的な情報が既にあります。 完全な移行インベントリを作成するには、リポジトリ内のデータについてより詳細な情報を取得する必要があります。
次に、以下の手順に従って、各リポジトリの移行インベントリに次のデータを追加します。
- 最も大きいファイル (1 つの "BLOB") のサイズ
- すべてのファイル (複数の "BLOB") の合計サイズ
Git 以外のバージョン コントロール システムを使っている場合、またはファイルがバージョン コントロール システムで一切追跡されていない場合は、まずリポジトリを Git に移動します。 詳しくは、「ローカルでホストされているコードを GitHub に追加する」を参照してください。
次に、オープンソース ツールの git-sizer を使って、リポジトリ用にこのデータを取得します。
前提条件
git-sizerをインストールする。 詳しくは、github/git-sizer リポジトリを参照してください。git-sizerがインストールされていることを確認するには、git-sizer –versionを実行します。git-sizer release 1.5.0のような出力が表示されれば、インストールは成功しています。jqをインストールする。 詳しくは、jqドキュメントの「jq のダウンロード」を参照してください。jqがインストールされていることを確認するには、jq –-versionを実行します。jq-1.6のような出力が表示されれば、インストールは成功しています。
git-sizer を使ってリポジトリのサイズを測定する
- 移行元からリポジトリを複製するには、
git clone --mirrorを実行します。 - リポジトリを複製したディレクトリに移動します。
- リポジトリ内で最も大きいファイルのサイズをバイト単位で取得するには、
git-sizer --no-progress -j | jq ".max_blob_size"を実行します。 - リポジトリ内のすべてのファイルの合計サイズをバイト単位で取得するには、
git-sizer --no-progress -j | jq ".unique_blob_size"を実行します。 - 上記の手順の値をインベントリに追加します。
移行の種類について
移行の実行時に利用できるアプローチが 3 つあり、移行忠実度のレベルが異なります。
| 移行の種類 | 定義 | 要件 |
|---|---|---|
| ソース スナップショット | コードの現在の状態をそのまま移行しますが、リビジョン履歴は含めません。 | コードがバージョン コントロール システム (VCS) で現在追跡されていない場合でも、すべての移行元と移行先に対して可能です。 |
| ソースと履歴 | コードの現在の状態とそのリビジョン履歴を移行します。 | Git で変更を追跡している場合や、移行前にバージョン コントロール システムを Git に変換できる場合に可能です。 |
| ソース、履歴、メタデータ | コードの現在の状態とそのリビジョン履歴に加えて、issue や pull request、設定などのコラボレーション履歴を移行します。 | 専門ツールが必要ですが、すべての移行パスで使用できるわけではありません。 |
完了する移行の種類を決定する際に、Organization のニーズと使用可能なツールを検討してください。
リポジトリによって使いたい戦略が異なる場合があります。 たとえば、履歴が重要ではない古いアーカイブ済みのリポジトリがある場合もあれば、最もアクティブなコードに忠実度の高い移行が不可欠な場合もあります。
さまざまな移行サポート モデルについて
GitHub から専門的なサポートを受けることなく、当社のドキュメントのみを使って独自の移行を計画および実行する "セルフサービス移行" を完了するように選ぶことができます。
または、GitHub の Expert Services チームまたは GitHub パートナーと一緒に作業することもできます ("エキスパート主導の移行" と呼びます)。 エキスパート主導の移行を使うと、これまで数十から数百回もの移行を実行したエキスパートの知識と経験を活用でき、セルフサービスでは利用できない追加の移行ツールにアクセスできます。
大量のデータを移行する場合は、エキスパート主導の移行から恩恵を受けられる可能性があります。 たとえば、何千ものリポジトリを移行する場合や、サイズが 5 GB 以上あるような複雑なリポジトリがある場合は、Expert Services とつながることをお勧めします。
| セルフサービス | エキスパート主導 | |
|---|---|---|
| ドキュメントへのアクセス | ||
| GitHub のあらゆるツールへのアクセス | ||
| サポート対象のトピック |
|
|
| コスト | 無料 | 詳しくは、Expert Services にお問い合わせください |
エキスパート主導の移行について詳しくは、アカウント担当者または Expert Services にお問い合わせください。
使うツールを決定する
移行を計画するには、移行先と移行元を検討してください。 これらの考慮事項で、移行のパスが決まります。詳細については、「GitHub への移行パス」を参照してください。
移行先の Organization 構造を設計する
GitHub では、各リポジトリは Organization に属します。 Organization は、高度なセキュリティと管理機能を使って、企業とオープンソース プロジェクトが一度に多くのプロジェクト間で共同作業ができる共有アカウントです。 詳しくは、「Organizationについて」を参照してください。
初めて GitHub を採用する場合でも、既に GitHub を使っている場合でも、一度停止して、移行後に Organization とリポジトリに最も効果的な構造を検討します。 選ぶ設計によって、コラボレーションと検出を最大化して管理上の負担を最小限に抑えることもあれば、不要なサイロや管理オーバーヘッドが作成されることもあります。
Organization の数を最小限に抑え、5 つのアーキタイプのいずれかに従って構成することをお勧めします。 詳しい説明については、「エンタープライズ内の組織を構成するためのベスト プラクティス」を参照してください。
すべてのリポジトリに対してドライ ラン移行を実行する
計画を続ける前に、すべてのリポジトリを含むドライ ラン移行を実行します。 包括的なドライ ランを実行すると、次のことができます。
- 選んだツールがリポジトリに対して機能することを確認する
- ツールが要件を満たしていることを確認する
- 移行されるデータと移行されないデータを正確に把握する
- 移行にかかる時間を把握して、運用環境の移行をスケジュールする
ドライ ラン移行に固有の作業はありません。 通常の移行を実行してから、移行先のリポジトリを削除するだけです。
移行前と移行後の手順を計画する
リポジトリの移行は、大規模な移行プロセスの手順の 1 つにすぎません。 他にも必要な手順があり、場合によってはデータや設定を手動で移行する必要があります。
移行に必要な手順の完全な一覧は、固有の状況によって異なりますが、すべての移行に適用される移行前の手順がいくつかあります。
- 今後の移行とそのタイムラインについて事前にユーザーに知らせる
- 移行が行われる直前にリマインダーを送信する
- チーム用に GitHub でユーザー アカウントを設定する
- 新しいシステムを指すようにローカル リポジトリを更新する手順をユーザーに送信する
すべての移行に適用される移行後の手順もあります。
- 移行が完了したことをユーザーに知らせる
- 移行先のユーザーにアクティビティをリンクする
- 移行元の使用を停止する
移行の計画時に考慮すべきその他の手順を次に示します。
継続的インテグレーション (CI) と継続的デリバリー (CD) を移行する
GitHub 製品間を移行する場合、CI/CD に GitHub Actions を既に使っていて、GitHub Actions を使い続けるなら、作業はあまりありません。 リポジトリ内のワークフロー ファイルは自動的に移行されます。 セルフホステッド ランナーを使う場合は、GitHub の新しい Organization でこれらを設定して、ワークフローを実行できる状態にする必要があります。
GitHub Actions を使っていない場合は、状況が複雑になります。 同じ CI/CD プロバイダーを使い続ける場合は、プロバイダーが GitHub と互換性があることをチェックし、プロバイダーを新しい Organization とリポジトリに接続する必要があります。
GitHub Actions への切り替えを計画している場合、リポジトリの移行と同時に行うことはお勧めしません。 代わりに、後日、CI/CD の移行を別の手順として実行します。 これにより、移行プロセスの管理が容易になります。 移行する準備ができたら、「GitHub Actionsへの移行」を参照してください。
統合を移行する
社内開発されたか、他のベンダーから提供されているコード ホスティング プロバイダーとの統合を使っている可能性が高いです。
既に GitHub を使っている場合は、新しい Organization とリポジトリを指すように統合を再構成する必要があります。 統合がベンダーから提供されている場合は、ベンダーに連絡して手順を確認してください。 統合が社内開発された場合は、新しい Organization で統合を再構成し、新しいトークンとキーを生成します。
GitHub を初めて使う場合は、お使いの統合が GitHub と互換性があるかどうかをチェックしてから再構成します。 社内開発された統合を使っている場合は、GitHub API で動作するように書き直します。 詳しくは、「GitHub REST API に関するドキュメント」を参照してください。
移行先のユーザーにアクティビティをリンクする
コラボレーション履歴やメタデータ、コードも移行する場合は、移行先の新しい ID にユーザーのアクティビティをリンクする必要があります。
たとえば、@octocat が お使いの GitHub Enterprise Server インスタンス で issue を作成し、GitHub Enterprise Cloud に移行するとします。 GitHub Enterprise Cloud では、@octocat のユーザー名がまったく異なる可能性があります。 帰属プロセスを使うと、ユーザー アクティビティをこれらの新しい ID にリンクできます。
帰属のしくみは、ツールによって異なります。
ghe-migrator、gl-exporter、またはbbs-exporterを使っている場合は、事前にデータを属性付けする方法を決定し、データをインポートするときにマッピング ファイルを含めます。- GitHub Enterprise Importer を使っている場合、データは "マネキン" と呼ばれるプレースホルダー ID にリンクされ、データの移行後にこの履歴を実際のユーザーに割り当てることができます。 詳しくは、「GitHub Enterprise Importer のマネキンの回収」を参照してください。
チームとアクセス許可を管理する
ほとんどのお客様は、チームを使ってリポジトリへのアクセスを管理します。 チームでは、Mona に直接リポジトリへのアクセス権を付与する代わりに、エンジニアリング チームに Mona を追加し、エンジニアリング チーム全員にリポジトリへのアクセス権を付与できます。 詳しくは、「Team について」を参照してください。
リポジトリを移行する前に、チームを作成し、チーム メンバーを追加できます。 ID プロバイダー (IdP) を使ってメンバーを管理するには、チームを IdP グループにリンクします。 詳しくは、「Team をアイデンティティプロバイダグループと同期する」を参照してください。
ただし、リポジトリを移行するまでは、チームをリポジトリにアタッチすることはできません。