この記事はSRE Advent Calendar 2023の１日目の記事です。
今回は業務で「GitHubリポジトリをあるorganization（以下、org）から別のorgへ移行させる」ということをやったので、その時のお話をさせていただきます。
何をするのか？
もう少し、何を目標としていたのか？を具体的に書くと、現在リポジトリ群が所属しているorgからGitHub Enterprise Cloud（以下、GHEC）配下に作成したorgへ移行させる、ということをやろうとしたお話になります。
GHECに移行するモチベーションとしてはGitHub Copilot for Businessが利用できたり、SAML SSOを利用できたりするというメリットを受けることが出来るからですね。（開発者にとってはCopilotが理由として大きいかも）
移行前の状況
移行前は以下のような状況でした。
- 自分が関わっていて移行対象となるGitHubリポジトリが10個
- 共通のPAT（Personal Access Token）を払い出すbotアカウントあり
- 外部の業務委託でお手伝いいただいている方のアカウントあり
- orgに紐付いたGitHub Projectsが２つ、特定のリポジトリに紐付いたProjectsが１つ
- CI/CDはGitHub Actions、CircleCI、ArgoCDなどを利用
- その他、GitHubリポジトリと紐付いている自作のツール類やGoogle CloudのCloud Functionsなどが存在している
- 移行先のorgはOktaを利用したSSOを設定
色々と移行に際して引っ掛かりそうなポイントが幾つかありそうですね。何となく察しがつく方もいらっしゃるかもしれませんが、後々躓きポイントも説明していきます。
作業開始、その前に
早速移行させるぞ〜〜〜・・・とはいかず、まずは影響を調べたりなどの事前調査からですね。移行先orgを作成したり、作ったorgをGHEC配下にしたりは今回は省略させていただきます。
事前調査もすべてを隈なく調べ切れるならいいのですが、それでもどこかヌケモレが発生することが考えられます。また、移行に際して締切日が設定されていたため、どこが破綻すると一番まずいか？を開発チームと話し、「サービスのデプロイ」「GitHub Projectsが使える」の２つが破綻するとまずいとのことで、そこは徹底して調査するようにしました。
調査
GHEC配下の移行先orgにリポジトリを移行すると一体何が起こるのでしょうか？ザザッと箇条書きにしてまとめてみます。
- リポジトリURLが変わる
- issue, PR, wikiなどの情報は移行先のリポジトリに受け継がれる
- 移行先orgに改めてGitHub Appをインストールし直す必要あり
- OktaでのSAML SSOが設定されているため、移行先orgに招待するユーザーはOktaアカウントを持っていることが必要
- orgと紐づいているGitHub Projectを移行させる
- Teamsもorgに紐づいているので新しく作成する
事前情報としてササッと調べた結果、このような感じで思った印象は「割と色々やらなきゃならんな」でした。とはいえ、設けられた締切日には十分間に合うんじゃないかな〜という感じでありました。
さて、次に移行対象となるGitHubリポジトリの洗い出し、デプロイのために使っていたCircleCIについての調査をやっていきます。リポジトリの洗い出しは特に問題はなかったのですが、CircleCIでは新しくorgを作成する必要があり、こちら新orgを作ってさえしまえば特に問題起きないだろうなと思いきや、作業後に躓きポイントがあったのでこちらも後ほど説明します。
CIといえばGitHub Actionsで、共通して利用するようなActionsは呼び出し元とは別リポジトリで管理していて、例えば以下のような感じでした。
ここの、 uses で指定している old-org を new-org と移行先org名にしないといけません。
あとはスマートフォンアプリも開発していて、その中で利用しているBitriseも調査しました。こちらはBitrise側で管理しているリポジトリURLを変更する必要があり、詳細は以下のリンク先に書いております。
以前記事にした「開発環境の使用状況分かるくん」など、自作ツールでデプロイに紐づくところも移行することで影響が出ないか調査しました。いくつかのツールでbotアカウントが生成したPATを使っていましたので、botアカウントを移行先のorgに追加するのを忘れないようにすれば良さそうです。
ここまでがCI/CDなどデプロイに関する調査でした。次にGitHub Projectsについて調査しましょう。
リポジトリに紐づいているGitHub Projectsは特に何もせずともリポジトリ移行すればOKなのですが、orgに紐づいているGitHub Projectsはそうはいきません。
調査した結果、Project自体はorgを跨いでコピーすることが出来てビューやフィールド、ドラフトissueなどもコピーされるようです。
ただし、リポジトリに作成されてProjectに紐づけているissueはコピーでは反映されず、カスタムフィールドを利用している場合はそちらもコピーされないので（弊チームではスクラムのポイントをissueに割り振るのに使用）、ここはスクリプトなりでGitHub APIを叩いて何とかする必要がありそうです。
一旦はここまでが事前に定義した必須条件であるデプロイとGitHub Projectsの調査になります。
この他にも
- Cloud FunctionsでリポジトリURLを指定しているところの修正
- Cloud Buildのトリガーである接続リポジトリの修正
- ドキュメント類の修正
- 移行後のSlack通知の再有効化
- 外部の業務委託の方のOktaゲストアカウントの払い出し
- botアカウントをoutside collaboratorとして追加
- SSHキー、PATのSSO設定をする
- 作業後のチームメンバーへの共有事項をまとめる
などの対応が必要という調査結果となりました。
一つ注意が必要なのは、今回諸々の事情からbotアカウントをoutside collaboratorで追加することになりましたが、本来であればGitHub Appを作成しそちらを使うべきであります。また、 Personal access tokens (classic) を使っている場合は特に気にすることはないのですが、 Fine-grained personal access tokens を使っている場合はoutside collaboratorではリポジトリなどに権限を持ったトークンを生成できませんので、そこはご注意ください。
作業開始
ここまでで必要な分は調査できましたので、事故が無いように誰も触らない休日に移行作業を開始しました。
リポジトリ移行
なにはともあれ、まずはリポジトリ移行を行いましょう。
GitHubのDanger Zone触るのが初めてだったので、多少ビビりましたがこちらは特に問題なく完了。
botアカウントをoutside collaboratorとして追加
次に、botアカウントをoutside collaboratorとして追加しましょう。こちらは移行したリポジトリの Collaborators and teams 設定からbotアカウントを追加すればOKです。
移行後のSlack通知の再有効化
このあたりで忘れないようSlack通知を再有効化しておきました。Slack上で実行するコマンドとしてはこんな感じ。
/github subscribe new-org/hoge issues, pulls, commits, releases, deployments, reviews, comments
SSHキー、PATのSSO設定をする
これは個人アカウント、botアカウント、メンバー各々のアカウントのすべてで必要な作業なのですが、移行先orgがSSOを利用しているためGitHubに登録しているSSHキー、生成しているPATで Configure SSO というSSO設定が必要になります。
Teamsを再作成
移行元orgで作成していたTeamsを移行先orgでも再び作成し、移行したリポジトリに追加したりしておきましょう。幸いにも弊チームでは扱うTeamsの数が数個だったので手作業で移行しましたが、Teamsの量が多い方は gh コマンドなどを駆使して自動化しましょう。
リポジトリURLに依存している箇所を修正
- ドキュメント類
- Cloud FunctionsでリポジトリURLを指定しているところ
- Cloud Buildのトリガーである接続リポジトリ
- GitHub Actionsの呼び出し先のリポジトリURL
- Bitriseで設定しているリポジトリURL
をガガッと移行先org名に修正しておきました。機械的にパパっと置換していきましょう。
RenovateのGitHub Appを再連携
ここで事前調査と違ったタスクが出てきました👀
これはGitHub Appを改めてインストールしていた際にRenovateだけ再連携の必要があり、やっておきました。連携後にコンソール画面からその後の動作をどうするか？を聞かれると思いますが、特に何もしない的な選択肢を選んでおくと良さそうです。
GitHub Projectsの移行
さて、やってきましたGitHub Projectsの移行の時間です。
こちらは事前調査から
- Projectを移行先orgへコピー
- 紐付けていたissueを再紐づけ
といった作業が必要なことは分かっていました。で、スクリプトが必要というお話でしたね。
幸いなことに、社内の他チームの方が組んでらっしゃったスクリプトを参考に、少し手直しをして作成しました。それがこちら。
やっていることは gh コマンドを使って、移行元orgのProjectから必要な情報であるissueやfield, custom fieldを移行先orgのProjectに移行しているといった感じですね。
スクリプトも用意できましたので、作業再開しましょう。まずはスクリプトのコメントにも書いてある通り、 gh コマンドで現在のProjectの状態を backup.json として保存しておきます。
その後、移行したいGitHub Projectsのメニューから Make a copy を選んで、移行先orgへコピーしましょう。
ドラフトissueもコピーしておきたいので、 Draft issues will be copied if selected は忘れず選択しておきます。
移行先のProjectが問題なくコピーされていることを確認したら、スクリプトを実行してissueの紐付けなどやっておきましょう。
で、調査段階の時に漏れていたことがProjectのIDを指定して実行する自作ツールが幾つかあり、これらのID修正もやっておきました。もし、Project IDを使ってゴニョゴニョしている方はお気をつけ下さい。
確認
最後にデプロイフローがきちんと動くかどうかの確認をして終了になります。
起こったこと
さて、ここまでやったことをザッと書いていきましたが、もちろん作業中・後に色々と問題も起こりました。ここでは起こった問題を書き残していきます。
CircleCIのorganizationに紐付いたContext variablesを移行し忘れていた
デプロイフローの確認時に発覚したのですが、デプロイ中にSlack通知を飛ばすところがあり、そこが動いておりませんでした。アレー？と思い調べてみると、CircleCIのorganizationに作成していたContext variablesに登録していたAPI Tokenを移行しなくてはいけないのをすっかり忘れておりました。うっかり。
CircleCIのProject, Pipelineなどが見れない
移行後、チームメンバーに触ってもらっている時に発覚。これについては原因自体は謎なのですが、CircleCIのProjectやPipelineが一切見れないという状況になっておりました。
云々かんぬん試してみたのですが、結論としてCircleCIの再ログインを行うと何故か再び見れるように。何故に🤔
Bitriseのworkflowが走らない
コードをコミットしたらBitriseのworkflowが走り、コードの静的解析をするのですがそこが全く動かず・・・
Bitriseのappの設定を確認すると、何故か GitHub Checks の項目がdisabledになっていたのでenabledにすることで解決。
リポジトリに紐付けたTeamの権限間違い
これは凡ミスなのですが、リポジトリに紐付けたTeamの権限が軒並みReadになっていてチームメンバーからご指摘が。申し訳ない・・・
ただ、ありがちなミスではあるのでご注意を。
まとめ
GitHub organizationの移行という中々体験出来ないことが体験でき、経験になりました。こういう作業は難度の割にトチると業務が滞るので結構神経使いますね😇
この記事が、今後organizationの移行する方の参考になれば幸いです。
次は @shu-kobさんによる「ブロックチェーンノード運用の苦労話」です！
