初めに
GitHubではリポジトリを別のユーザーやOrganizationに移行することができます。最近、リポジトリを別のOrganizationに移行する機会があったので、移行手順について記載していきます。
GitHubリポジトリ移行時の流れ
GitHubリポジトリ移行時の大まかな流れは以下の通りです。今回の記事では主に2~4までの手順を記載して行きます。
- 必要に応じてwikiやReadmeの更新
- バックアップ作業
- Gihubリポジトリの移行
- GitリモートURL・サブモジュールの設定の更新
- 必要に応じてGitHubリポジトリと連携しているサービス（AWSやSlack等）の再設定を実施
バックアップ作業
移行による不測の事態に備える為、リポジトリのバックアップ作業を行います。GitHub上でバックアップ用のリポジトリを作成しておきます。リポジトリは空の状態でREADME・LICENSEは追加しません。「リポジトリ名-archive」など対象のリポジトリがバックアップとわかる命名にすると良いかと思います。
バックアップの為に、git clone --mirrorを使用します。--mirrorオプションはリモートリポジトリの完全なミラーコピー（複製）をローカルに作成するためのコマンドです。ブランチ、タグ、すべてのrefs含めてクローンされますが、プルリクエストは引き継がれません。
バックアップ元のリポジトリURLを指定して、ローカルにリポジトリ情報を取得します。
git clone --mirror <元リポジトリ URL>.git
cd repo-name // ディレクトリに移動
push先をバックアップ先リポジトリに設定します。
git remote set-url --push origin <バックアップ先リポジトリ URL>.git
設定ミス防止のため、URLを確認します。
git remote -v
======== 出力例 ========
origin https://github.com/old-org/repo-name.git (元リポジトリ URL)
origin https://github.com/new-org/repo-name.git (バックアップ先リポジトリ URL）
バックアップ先へ全てpushします。
git push --mirror
push時、送信データが大きい場合は、以下のエラーが発生します。
error: RPC failed; HTTP 400 curl 22 The requested URL returned error: 400
send-pack: unexpected disconnect while reading sideband packet
これはGitが大きなパックアップデータを送信しきれなかったことによるもので、1つのファイルサイズの上限を上回っているため、この上限を増やす必要があります。
git config http.postBufferを使用して、150MBに設定して再度pushします。
git config --global http.postBuffer 524288000
push後はローカルのリポジトリデータは不要なので削除してしまって良いかと思いますが、もしローカルで作業を続けるリポジトリに対して誤push防止のため、no_pushを設定します。
git remote set-url --push origin no_push
git remote -v
======= 出力例 =======
origin https://github.com/org/repo.git (fetch)
origin no_push (push)
移行前に確認しておきたいこと
GitHubリポジトリの移行をスムーズに進めるために、事前に以下の項目を確認しておくと安心です。
Admin権限
移行作業者は移行元リポジトリおよび移行先Organazationの両方でAdmin権限（管理者アクセス権）が必要です。Admin権限が不足している場合、移管操作時に次のようなエラーが表示されてしまい、移行が完了しませんので、移行先OrganazationのOwner権限を持つユーザーに一時的に権限を付与してもらう必要があります。
You must have admin rights to transfer this repository.
-
移行元リポジトリ
-
Settings > General > Danger Zoneにある「Transfer ownership」ボタンが表示されていることを確認します。
-
-
移行先（Organization）
- 移管先のOrganizationに対して リポジトリの受け入れを承認できる権限（通常はOwnerまたはAdmin）が必要です。
移行先、Organizationのプランを確認
移行先のOrganizationがフリープランの場合、リポジトリ移行時に失われる情報についての警告が表示されます。Pull RequestのReviewers/Approvers、wikiの情報、Draft状態のPRが失われるようですが、この時表示される警告文以外、公式のドキュメントで明確な記載がないため、可能であれば有料プランに変更してもらうのが安全です。
外部コラボレータの消費枠の確認
外部コラボレーターとは「Organizationの正式メンバーではないが、1つ以上のリポジトリにアクセス権限を持っているユーザー」のことを指します。ポジトリを移行する際、移行先のOrganizationで引き続き作業を行う外部コラボレーターがいる場合は、その人数分だけ外部コラボレーターの枠を消費してしまうため、移行先Organizationでの 外部コラボレーターの上限数に空きがあることを確認します。もし不足していた場合は、シート数についてのエラーが発生して移行処理がブロックされます。
リポジトリ移行
リポジトリの移行自体はgithub公式の機能を使用して簡単に移行することができます。リポジトリを移行すると、そのIssue、プルリクエスト、Secrets、Wiki、Star、Watchしているユーザも移行されます。
移行対象のリポジトリから Settings > General > Danger Zone >Transferに移動します。
移行先のOrganization Nameを入力して、「I understand〜」のボタンを押下します。GitHub 上から移行をリクエスト後、移行先「Organization」のOwner権限のある方に承認メール通知が届くため、承認してもらいます。承認後、https://github.com/<new-org>/<リポジトリ名>にアクセスしてリポジトリが新Organizationで表示されることを確認できれば、移行作業は完了です。
移譲先のOrganizationで移譲前にRepositoryに対して設定した情報（commit、branch、Pull request、Secrets等）が移譲後にも引き継がれていることも確認します。
移行後の対応（GitリモートURLの更新）
githubの移行が完了した後は、各リポジトリに設定されているGitリモートURLが移行前の旧リポジトリのURLのままのため、新URLに更新していきます。
Githubの公式ドキュメントでも混乱を避けるため、既存のローカルクローンを新しいリポジトリのURLを指すように更新することを強くお勧めています。
GitリモートURLの更新はgit remote set-urlを使用します。
git remote set-url origin git@github.com:<新Org>/<リポジトリURL>.git
新Organizationに変わっていることを確認します。
git remote -v
もし、リポジトリでサブモジュールを設置していた場合は、.submoduleの設定が以下のようになっているため、変更する必要があります。
cat .submodule
[submodule "<リポジトリ名>"]
path = <リポジトリ名>
url = git@github.com:<旧Org>/<リポジトリURL>.git
git config -fで.gitmodulesのURLを更新します。
git config -f .gitmodules submodule.url git@github.com:<移行先Org>/<リポジトリURL>.git
.gitmodulesが修正されていれていれば変更したBranchをpushします。
git commit -m "Update submodule URL to new organization"
サブモジュールのリモートURLも変更します。
git remote -v # 現在設定されているURLの確認
git remote set-url origin <新Org>/<リポジトリURL>.git # リモートURLを変更
メインブランチに移動してsubmodule変更済みのbranchを取り込み、新URLになっていることを確認します。
git pull origin <ブランチ名> # submodule変更済みのbranchを取り込み
git submodule sync # サブモジュールの設定を同期
cat .gitmodules # .gitmodulesが新URLとなっていることを確認
git remote -v # 新URLになっていることを確認
移行手順はこれで終了となります。リポジトリの移行自体はGithub上の操作で簡単に引き継ぐことができますが、事前確認を怠ると当日移行できないことが発生するので、注意が必要です。
参考文献
Discussion