Zenn
🧰

Check! GitHub Enterprise Importerの手順を確認する

2023/09/30に公開
GitHub
tech

Prologue

こんにちは、@dz_ こと、岩永かづみです。

GitHub Enterprise Importer(GEI)が2023年6月にリリースされました。これは、次のサービスからGitHub.comに対して、リポジトリまたはOrganizationを移行できるツールです。

  • GitHub.com
  • GitHub Enterprise Server(GHES) 3.4.1以降
  • Azure DevOps（クラウド版）
  • Bitbucket（Bitbucket Server, Bitbucket Data Center 5.14以降）

ドキュメントはこちらからご確認ください。

実際に作業を進める場合は慎重に、ドキュメントをよく確認いただいた上で実施する必要がありますが、最初にイメージがつきにくいと思うので、ポイントをまとめます。

移行を計画する

ほとんどの場合、すでに運用している環境を移行する要件であり、慎重に段取りを整理する必要があります。次の観点でGEIでできることを理解し、移行の要件を整理し、GEIがカバーしておらず手作業で行わなければならない作業は何かを把握します。

  • Organization単位か、リポジトリ単位か
  • 移行に割ける時間
  • 移行できる・移行できない項目
  • 移行できる権限を持つアカウント

詳細はドキュメントをご参照ください。

移行元の状況を知る（GitHub Migration Analyzer）

移行元のOrganizationやリポジトリの状況の確認するにあたり、完全に調査できるツールはないのですが、手始めに概要を把握するには、GitHub Migration Analyzerを利用できます。

GitHub Migration Analyzerを利用すると、これらの情報を集計することができます。

Repository metrics

項目 説明
Repository Name リポジトリ名
Last Push Date 最後にpushした日
Is Archived? アーカイブされているか
Number Of Pull Requests プルリクエストの数
Number of Issues Issuesの数
Number of Projects （旧）Projectsの数（※）
Number of Discussions Discussionsの数
Number of Packages Packagesの数
Number of Releases Releasesの数
Wiki Enabled Wikiの有効/無効
Size (KiB) リポジトリが占めるディスクサイズ（KiB）（実際のサイズと差異がある場合があります）

Organization metrics

項目 説明
Number of Members メンバーの数
Number of Projects （旧）プロジェクトの数（※）
Number of Repositories リポジトリの数
Repo with Most Pull Requests 一番多いリポジトリの数
Average Pull Requests プルリクエストの数の平均値
Repo with Most Issues 一番多いIssuesの数
Average Issues Issuesの数の平均値

※ 現行のGitHub Projects（v2）は含まれません。

移行できる・移行できない項目を確認する

下記のドキュメントで、移行できるまたは移行されない対象について列挙されています。数が多く、また最新情報を得るためにも、ドキュメントをご参照ください。

これらの情報を参考に、移行したい内容が網羅されているか、手動やほかの手段による移行が必要なものは何かをできるだけ洗い出しておきましょう。

注釈としては、次が挙げられています。

  • リポジトリの可視性はすべてプライベートに変更されます。
  • チームのメンバー構成は、移行されません。
  • @octo-org/octo-teamのようなチームの参照は、更新されません。CODEOWNERSなどの構成に影響があるかもしれません。
  • Branch protections rulesのうち、いくつかのルールは移行されません。詳しくはドキュメントをご参照ください。

移行作業ができるアカウントを確認する

移行作業を予定している担当者のアカウントが、移行に必要な権限を持つか確認しましょう。持たないのであれば、適任者が作業をするか権限の割当てを検討してください。

移行を実行するには、移行元と移行先の両方に十分なアクセス権が必要です。 リポジトリの移行の場合、移行先は Organization です。 Organization の移行の場合、移行先は Enterprise アカウントです。

テストを必ず行う

ドキュメントで指南されているように、本番の前に、試験的実行を行うことが強く勧められています。

次のような観点において、事前に対処できるよう、本番の状況を模した検証環境を用意ししっかり確認しましょう。

  • 計画通りに移行が完了できるか
  • どれくらいかかるか
  • 手作業による移行作業でトラブルはないか
  • これまで通り利用できる状態まで復元できるか
  • リポジトリ単位での移行の場合、中間スクリプトが生成されるのでそれらが意図通りか
  • テストで実施した移行ログを確認し、問題がないか

詳しくは、下記のドキュメントをご参照ください。

移行を実施する

移行の実施は、ドキュメントに従い進めます。手順は、移行対象によって異なります。詳しくはドキュメントをご参照ください。

大まかに次の流れで作業します。

  1. GitHub CLIおよび拡張機能をインストールする
    移行対象 拡張機能 サブコマンド
    GitHub.com github/gh-gei gh gei
    Azure DevOps github/gh-ado2gh gh ado2gh
    Bitbucket Server github/gh-bbs2gh gh bbs2gh
  2. 移行元、移行先のPersonal Access Token(PAT)(classic)を準備する
  3. 移行コマンドを実行する
    • リポジトリ移行の場合は、各リポジトリ毎のスクリプトを生成し、それらを実行する
  4. 手作業の移行を行う

ここでは、GitHub.comからGitHub Enterprise CloudへOrganizationを移行する手順を簡単に紹介します。実行コマンドは次の通りです。

gh gei migrate-org --github-source-org SOURCE --github-target-org DESTINATION --github-target-enterprise ENTERPRISE

実行すると、次のようなログを生成し、移行が実行されます。

gh gei migrate-org --github-source-org SOURCE_ORG_NAME --github-target-org DESTINATION_ORG_NAME --github-target-enterprise ENTERPRISE_NAME

[2023-09-29 05:38:23] [INFO] You are running the latest version of the gei CLI [v1.1.0]
[2023-09-29 05:38:23] [INFO] GITHUB SOURCE ORG: SOURCE_ORG_NAME
[2023-09-29 05:38:23] [INFO] GITHUB TARGET ORG: DESTINATION_ORG_NAME
[2023-09-29 05:38:23] [INFO] GITHUB TARGET ENTERPRISE: ENTERPRISE_NAME
[2023-09-29 05:38:23] [INFO] Migrating Org...
[2023-09-29 05:38:29] [INFO] Migration in progress (ID: OM_awoejfoAOSIJFOIJRjreqaoijofjASJF1023948rAWIOjdojfoaerrj). State: QUEUED. Waiting 10 seconds...
[2023-09-29 05:38:41] [INFO] Migration in progress (ID: OM_awoejfoAOSIJFOIJRjreqaoijofjASJF1023948rAWIOjdojfoaerrj). State: PRE_REPO_MIGRATION. Waiting 10 seconds...
[2023-09-29 05:38:53] [INFO] Migration in progress (ID: OM_awoejfoAOSIJFOIJRjreqaoijofjASJF1023948rAWIOjdojfoaerrj). State: REPO_MIGRATION. 0/3 repo(s) migrated. Waiting 10 seconds...
[2023-09-29 05:39:05] [INFO] Migration in progress (ID: OM_awoejfoAOSIJFOIJRjreqaoijofjASJF1023948rAWIOjdojfoaerrj). State: REPO_MIGRATION. 0/3 repo(s) migrated. Waiting 10 seconds...
[2023-09-29 05:39:16] [INFO] Migration in progress (ID: OM_awoejfoAOSIJFOIJRjreqaoijofjASJF1023948rAWIOjdojfoaerrj). State: REPO_MIGRATION. 0/3 repo(s) migrated. Waiting 10 seconds...
...
[2023-09-29 05:41:11] [INFO] Migration in progress (ID: OM_awoejfoAOSIJFOIJRjreqaoijofjASJF1023948rAWIOjdojfoaerrj). State: REPO_MIGRATION. 3/3 repo(s) migrated. Waiting 10 seconds...
[2023-09-29 05:41:23] [INFO] Migration in progress (ID: OM_awoejfoAOSIJFOIJRjreqaoijofjASJF1023948rAWIOjdojfoaerrj). State: REPO_MIGRATION. 3/3 repo(s) migrated. Waiting 10 seconds...
[2023-09-29 05:41:35] [INFO] Migration in progress (ID: OM_awoejfoAOSIJFOIJRjreqaoijofjASJF1023948rAWIOjdojfoaerrj). State: REPO_MIGRATION. 3/3 repo(s) migrated. Waiting 10 seconds...
[2023-09-29 05:41:47] [INFO] Migration in progress (ID: OM_awoejfoAOSIJFOIJRjreqaoijofjASJF1023948rAWIOjdojfoaerrj). State: REPO_MIGRATION. 3/3 repo(s) migrated. Waiting 10 seconds...
[2023-09-29 05:41:59] [INFO] Migration in progress (ID: OM_awoejfoAOSIJFOIJRjreqaoijofjASJF1023948rAWIOjdojfoaerrj). State: REPO_MIGRATION. 3/3 repo(s) migrated. Waiting 10 seconds...
[2023-09-29 05:42:10] [INFO] Migration completed (ID: OM_awoejfoAOSIJFOIJRjreqaoijofjASJF1023948rAWIOjdojfoaerrj)! State: SUCCEEDED

コマンドの実行が完了すると、次のログが出力されているので、確認しましょう。

  • コマンドを実行したディレクトリに*.octoshift.log、*.octoshift.verbose.logが生成される
  • 移行先のOrganizationにgei-migration-resultsというリポジトリが作成され、各種ログが格納される
  • 移行先のリポジトリにMigration Logというタイトルのissueが作成され、ログが格納される

移行後、マネキンへユーザーを割り当てる

GEIのコマンドだけでは移行されない項目について、手作業で移行します。そのうち、ユーザーについては移行されておらず、「マネキン」として仮のユーザーが割り当てられているので、「マネキンの回収」をする必要があります。

マネキンの回収では、GitHub CLIまたはブラウザからの操作で、マネキンに対してユーザー割り当てます。

マネキンにユーザーを割り当てると、そのユーザーに招待が届きます。ユーザーが招待を承諾すると、マネキンの回収が完了します。

GitHub CLIを利用する場合、GitHub.comからの移行では、次のようにマネキンのリストを取得できます。

gh gei generate-mannequin-csv --github-target-org DESTINATION_ORG_NAME --output FILENAME.csv
[2023-09-29 09:33:39] [INFO] You are running the latest version of the gei CLI [v1.1.0]
[2023-09-29 09:33:39] [INFO] GITHUB ORG: DESTINATION_ORG_NAME
[2023-09-29 09:33:39] [INFO] OUTPUT: FILENAME.csv
[2023-09-29 09:33:39] [INFO] Generating CSV...
[2023-09-29 09:33:40] [INFO]     # Mannequins Found: 2
[2023-09-29 09:33:40] [INFO]     # Mannequins Previously Reclaimed: 0

出力されたCSVファイルはこのようになります。

mannequin-user,mannequin-id,target-user
USER_1,M_kgDOKLoYVw,
USER_2,M_kgDOKLoYWw,

target-userの列に、割り当てるユーザーを指定します。このCSVファイルを編集し、次のコマンドでマネキンの回収を実施します。Enterprise Managed Usersの場合は、--skip-invitationオプションを指定することで、招待をスキップすることができます。

gh gei reclaim-mannequin --github-target-org DESTINATION --csv FILENAME.csv

また、GitHub.com上でもマネキンの回収ができます。１人ずつ割り当てることになりますが、小人数であればこちらの方がわかりやすいかもしれません。

詳しくはドキュメントをご参照ください。

Epilogue

GitHub Enterprise Importerを使えば、大部分を移行できます。

ただし、GitHubの進化が速いゆえか移行しきれない部分もあるので、しっかり移行計画を立てテストを行い実施することが肝心です。安心して作業できるように準備を進めましょう。

Discussion