既存リポジトリ移行チェックリストと段階的手順

既存の『GitHub』リポジトリに標準化を入れる作業は、コードを移すだけでは終わりません。
私も最初の移行で、移行先に自動追加されたREADMEが原因で履歴がぶつかり、想定外の手戻りを出しましたが、そこで手順を組み直し、2回のリハーサルと切り戻し条件の明文化まで含めて設計したことで、停止時間を短く抑えられました。
この記事は、既存リポジトリへ新しい運用基盤を導入したい開発者やチーム管理者に向けて、何を移すのかを最初に固定し、コード・設定・運用ルールを棚卸ししたうえで、権限、CI/CD、Webhook、Pages、Secretsまで漏れなく点検する進め方を整理します。
既存ディレクトリをgit initで管理化する入口と、移行用の mirror push を使う実践例をつなぎ、フェーズ0から本番後の定着までを一気通貫で再現できる形に落とし込みます。
移行の成否は、派手なコマンドよりも、対象範囲の固定と段階的な切替設計で決まります。
『Checklist for Repository Migrations – GitHub Well-Architected』やGit - Git リポジトリの取得に沿って、明日からそのまま使える段階的移行テンプレートとして示します。

既存リポジトリへの導入で最初に決めること

3類型の定義と境界

このセクションで扱うのは、すでにコードや設定が存在する状態に対して、新しい運用ルール、ホスティング、管理方式を導入するケースです。
ゼロから新規リポジトリを作る話ではありません。
ここを曖昧にすると、読者によって「ローカルの作業フォルダを『GitHub』に載せたい話」と「『GitLab』から『GitHub』へ移したい話」と「コードは動かさずブランチ保護だけ入れたい話」が混ざり、必要な準備がずれていきます。

対象は次の3類型に切り分けると、一意に定められます。
1つ目は、既存フォルダをGit管理化してローカルから『GitHub』へ持っていく類型です。
これは git init で .git ディレクトリを作るところから始まりますが、その時点では既存ファイルはまだ追跡されておらず、初回の add と commit が要ります。
2つ目は、すでにどこかにあるリモートリポジトリを別ホスティングへ移す類型です。
『GitHub』からBitbucket、『GitLab』から『GitHub』のような移送がここに入ります。
3つ目は、コードの置き場所は変えず、ブランチ保護、CI、権限モデル、Secrets運用のようなルールだけを導入する類型です。

この3つは似て見えて、初手で確認すべきものが違います。
1つ目は「初回コミットの単位」と「既存ファイルの追跡範囲」が中心になります。
2つ目は「履歴をどこまで保つか」と「周辺機能を何ごと持ち替えるか」が中心です。
3つ目は一見いちばん軽く見えますが、実際には設定の依存関係が深く、境界を曖昧にすると燃えやすい領域です。
私も「運用ルールだけ入れる」つもりで着手した案件で、最初に『GitHub Actions』のSecrets整理が論点になり、そこから『Slack』通知用のWebhook、公開サイト用のGitHub Pages、環境ごとの権限制御まで連鎖的に見直すことになりました。
コードを移さないから小さい作業だろうと見積もると外れます。
範囲を先に固定して、「今回はブランチ保護とCIだけ」「PagesとWebhookも対象に含める」のように線を引くことが、トラブル回避の第一歩でした。

『GitHub』へ既存リポジトリを取り込む場面では、新規作成時にREADMEやLicenseを自動追加しないほうが安全です。
既存履歴と初期ファイルがぶつかると、導入前の段階で余計なマージが発生します。
前述のトラブルと同じで、どの類型かを決めることは、どの衝突を避けるかを決めることでもあります。

GitHub Actions ドキュメント - GitHub ドキュメント

docs.github.com

制約条件の棚卸し

類型を決めたら、次に詰めるのは手順ではなく制約です。
移行や導入の成否はコマンドの巧拙より、「止めてよいのか」「誰が承認するのか」「どこまで記録を残すのか」を着手前に言語化できているかで決まります。
GitHub Well-Architectedの移行チェックリストでも、権限、アクセスパターン、外部ツール、利用ワークフローを先に文書化する前提が置かれています。

まず明文化したいのは停止可否と許容停止時間です。
たとえば一括で切り替えるのか、段階的に進めるのかは、この条件でほぼ決まります。
短い停止時間を確保できるなら一括移行の設計が取りやすく、止めにくい運用なら新旧をしばらく併存させる案に寄ります。
ただし段階的移行はリスクを分散できる一方で、新旧両方のCIや通知経路を面倒見る期間が生まれるため、管理対象は増えます。
コード本体だけでなく、CI/CD、Webhook、Pages、Packagesまで対象に含めて考えないと、移行の途中だけ動かない部品が残ります。

関係者の洗い出しも早い段階で必要です。
開発メンバーだけで完結することは少なく、組織管理者、セキュリティ担当、インフラ担当、外部SaaSの管理者が絡みます。
『Sentry』のリリース連携やJiraのWebhook、『Slack』通知の受信先のように、リポジトリ外にある設定は所有者が別になりがちです。
ここを曖昧にすると、切替当日に「そのトークンは別チームしか更新できない」が発生します。

コンプライアンスや監査ログの要件も、後回しにすると設計をやり直す原因になります。
たとえば権限変更の記録を残す必要があるのか、リポジトリの移譲や削除に承認が要るのか、Secretsの取り扱いに監査証跡が必要なのかで、実施順序が変わります。
GitHub Enterprise CloudとGitHub Enterprise Serverのように監査やSSOの扱いが運用設計に効く製品では、ホスティング先の違いそのものが制約条件になります。

命名規則も見落としやすい項目です。
『GitHub』の新規リポジトリ名は最大100文字なので、既存のシステム名、部署名、用途、環境名を全部つないだ長い命名を前提にしていると、そのままでは入りません。
移行後に名前を詰め直すと、WebhookのURLや連携先のリポジトリ指定も巻き込みます。
技術的には小さな制約でも、運用では波及範囲が広いところです。

なお、GitHub の Free プランでも public / private にかかわらずリポジトリ数は無制限です。

Sentry Docs ｜ Application Performance Monitoring & Error Tracking Software

Self-hosted and cloud-based application performance monitoring & error tracking that helps software teams see cleare

docs.sentry.io

成果物と設定の対象表

範囲と制約が見えたら、次は「何を移すか」ではなく「何が成果物として残るか」を表にしておく段階です。
ここでいう成果物は、Gitの中身だけを指しません。
コード、履歴、タグに加えて、権限設定、CI/CD、Webhook、Pages、Packages、ドキュメントまで含めて、導入後に同等の運用が成立する状態を指します。
リポジトリ移行の現場で抜けやすいのは、まさにGitの外側です。

コード本体については、ファイルがあるだけでは足りません。
履歴とタグを残すのか、現行スナップショットだけでよいのかで、採るべき手段が変わります。
移行用の git clone --mirror は通常作業用のローカルコピーではなく、履歴や参照をまとめて運ぶためのベアコピーとして分けて扱う前提があります。
作業リポジトリと移行専用ミラーを混ぜると、検証中のpush先を取り違えやすくなります。

権限設定は、コード移送よりあとに考えると手戻りになります。
誰が管理者か、誰がpushできるか、保護ブランチに対してレビュー必須やステータスチェック必須をどう入れるかで、切替直後の開発速度が変わります。
『GitHub』のBranch protection rulesでは、レビュー必須、ステータスチェック必須、線形履歴、署名済みコミット要求、push制限などを組み合わせられます。
ルールだけ導入する案件でも、既存の権限モデルとぶつかれば作業は止まります。

CI/CDは、ワークフローファイルをコピーして終わりません。
『GitHub Actions』では permissions キーで GITHUB_TOKEN の権限を細かく制御でき、未指定の権限はアクセスなしになります。
つまり、移行前のCIが暗黙の強い権限で動いていた場合、導入後に同じYAMLでも失敗します。
Secretsも、リポジトリ、組織、環境のどこに置くかでアクセス範囲が変わります。
私が先に触れた案件でも、環境シークレットへ寄せるか組織シークレットへ寄せるかを決めないまま進めたため、デプロイ権限と通知権限の整理が途中でぶつかりました。
コード移行がない案件ほど、この種の設定差分が本丸になります。

Webhookと外部連携は、一覧化して初めて抜けが見えます。
GitHub Webhooksのペイロードは25 MBを超えると配信されないため、大きなイベントを前提に受信設計している連携は別手段も視野に入ります。
署名検証も、X-Hub-Signature-256 を使うのか、旧来の方式を残すのかで受信側改修が要ります。
『Slack』通知、Jiraのイベント受信、『Sentry』のリリース連携は、それぞれ設定画面が別で、管理主体も違うことが多いので、リポジトリ内の設定ファイルだけ見ても全体像は掴めません。

GitHub Pagesと『GitHub Packages』も対象表に含めておくべき領域です。
Pagesは公開サイトが絡むため、見た目が変わらなくても配信経路は変わります。
カスタムドメインを使っている場合、移譲時にDNSレコードを放置するとドメイン乗っ取りの危険が残るため、リポジトリ移譲の作業項目として扱う必要があります。
Packagesは認証方式や公開権限の整理が要り、『GitHub Actions』から publish しているなら registry-url とトークン権限の整合まで見なければ動作は再現できません。

文書も立派な成果物です。
README、.gitignore、運用ルール、ブランチ戦略、リリース手順が更新されていないと、設定だけ新しくなってもチーム運用は旧ルールのまま残ります。
特に「誰がどのブランチに直接pushできるか」「障害時にどこまで切り戻すか」のようなルールは、設定画面だけでは共有できません。
技術的な完了条件と運用上の完了条件を分けないためにも、成果物と設定の対象表を最初に置いておく意味があります。

移行方式を選ぶ: 一括移行・段階的移行・並行運用

移行方式は、コードをどの順番で運ぶかだけの話ではありません。
前のセクションで整理した「コード/履歴/タグ」「権限設定」「CI/CD・Webhook」「Pages/Packages」「ドキュメント」のどれを、いつ切り替えるかまで含めて決める必要があります。
GitHub Well-ArchitectedのChecklist for Repository Migrationsでも、権限、アクセスパターン、外部ツール、利用ワークフローを文書化したうえで、移行ペースを all at once か phased で計画することが求められています。
つまり、方式選びは好みではなく、停止制約と影響範囲から決める設計作業です。

実際に現場で進めると、小規模な repo なら一括で終えたくなりますし、それで問題ない場面もあります。
ただし分岐点になるのはファイル数より、GitHub Actions、保護ブランチ、Secrets、Webhook、外部 SaaS 連携がどれだけ絡んでいるかです。
リポジトリ本体は小さくても、CI と権限設計が複雑なら、一括切替の難度は一気に上がります。
筆者の現場では、主要 repo から段階的に進めたときが最も事故が少なく、バックエンドから先に移し、その後にフロント、最後にインフラ IaC へ進む順番で依存をほどくと、切替時の確認点を絞り込めました。

比較表: 一括 / 段階的 / 並行運用

まずは3方式の違いを、停止時間、失敗時の影響、チーム体制の観点で並べて見ます。
表は「どれが優れているか」を示すものではなく、「自分の制約がどの列に近いか」を見るためのものです。
小規模 repo でも、外部連携が多ければ段階的や並行運用の列を読む価値があります。

一括移行は、条件がそろえば最も迷いが少ない方法です。
repo が1つか2つで、チームも小さく、停止時間を確保できるなら、切替日を決めてまとめて移すほうが運用は単純です。
特に、リポジトリそのものは小さく、README や初期ファイルの競合も避けられ、保護ブランチや GitHub Actions の設定差分も限られるなら、一括で片づける合理性があります。

一方で、repo のサイズよりも厄介なのは周辺設定です。
たとえば GITHUB_TOKEN の権限、環境シークレット、セルフホストランナー、Slack や Jira への Webhook、Sentry のリリース連携が入っていると、切替対象はコードではなく運用基盤まで広がります。

並行運用は慎重な方式ですが、同じ作業を二重に持つ期間が発生します。
CI が二本立てになり、通知も新旧で流れ、権限設定も両方を保つ必要があります。
監査や可用性の要件がある基幹運用では有力ですが、通常の開発チームでは、並行運用そのものが新しい負担になることも多いです。
そのため、並行運用は「安全そうだから選ぶ」のではなく、旧環境を残すことでしか検証できない論点があるかで判断したほうがぶれません。

段階的移行が効く条件

段階的移行が最も効くのは、停止時間を取りにくく、依存関係が多く、影響範囲を事前に読み切れないケースです。
コード本体だけなら一括で移せそうに見えても、実際には PR レビューの流れ、ブランチ保護、Actions の実行権限、Webhook の通知先、Pages や Packages の公開経路が絡みます。
こうした要素が多いほど、フェーズを分けたほうが確認対象を絞れます。

特に、複数 repo が連動している構成では、段階的移行の効果が出やすくなります。
バックエンド API の repo、フロントエンドの repo、IaC の repo が別れている場合、どれから動かすかで難度が変わります。
筆者の現場では、主要 repo から段階的に進める方針が最も安定していて、バックエンドから先に切り替えると、認証、データ取得、CI の中核部分を早めに確認できます。
その後にフロントを移すと API 側の前提が固まっているので差分が見えやすく、IaC を最後に置くと、本番基盤に触るタイミングを絞れました。
依存をほどく順番を持っているかどうかで、段階的移行の実効性は変わります。

もう1つの向く条件は、周辺設定が複雑なケースです。
たとえば保護ブランチのレビュー要件が team ごとに違い、環境シークレットも repo 単位と environment 単位で分かれていて、GitHub Actions の permissions も job ごとに調整しているような構成です。
この場合、コード移行と同じ日に全部をそろえるより、まず repo と履歴、次に権限、次に CI/CD、次に外部通知という順で切るほうが、障害箇所を切り分けやすくなります。

段階的移行は、切り戻し設計と相性が良いのも利点です。
フェーズ単位で進めれば、「どこまで戻すか」を repo 単位、設定単位で定義できます。
移行計画で切り戻し手順を先に決めるべきだとされるのはこのためです。
リハーサルでも、フェーズごとに確認項目を回せるので、1回目で出た不足を2回目で潰しやすくなります。
全体を一度に試すより、失敗の意味が読み取りやすい構成になります。

自動化の限界と人的レビューポイント

移行作業では、自動化できる部分と、人が見ないと抜ける部分を分けて考える必要があります。
ミラーコピー、ブランチ作成、設定ファイルの転記、Actions ワークフローの雛形生成までは自動化の恩恵を受けやすい領域です。
反対に、権限の妥当性、通知の意味、レビュー手順の整合、切替後のチーム運用は、最終的に人の判断が残ります。

ここで気をつけたいのが、AI や自動変換ツールへの過信です。
RepoMod-Benchは Git の移行ベンチマークではなく、実在の大規模 repo に対する自動コード変更の通過率を見た研究ですが、背景知識としては示唆があります。
21 の real-world repositories、8 言語、1.6M LOC、11,616 テストケースで構成され、10K LOC 未満では平均 91.3% pass rate だった一方、50K LOC 超では平均 15.3% まで落ち、162K LOC の uncrustify では全エージェントが 0% でした。
つまり、大きな repo ほど「自動でまとめて直す」発想は当たりにくくなります。
移行でも同じで、YAML や設定ファイルを一括変換できても、その設定がそのまま組織運用に合うとは限りません。

人的レビューを入れるべき点は、少なくとも3つあります。
1つ目は権限です。
Admin、Maintain、Write の割り当てだけでなく、保護ブランチのレビュー必須数、status checks、force push の可否が現行ルールと一致しているかは、人が業務フローに照らして見る必要があります。
2つ目は CI/CD と Secrets です。
ワークフローが動くかだけでなく、GITHUB_TOKEN の permissions が不足していないか、逆に広すぎないか、environment secrets の注入先が想定どおりかを確認しないと、移行後にデプロイだけ失敗する形で表面化します。
3つ目は外部連携です。
Slack 通知、Jira 連携、Sentry のリリース追跡は、イベントが飛ぶだけでは足りず、誰がどの情報を受け取る前提かまで整っているかを見る必要があります。

実際にやってみると、自動化の成否より、「どの結果を人が承認したか」を残すほうが後工程で効いてきます。
たとえば repo 作成、ミラー push、ブランチ保護設定まではスクリプトでそろえ、その後にレビュー担当が PR 作成、Actions 実行、Webhook 通知、リリース連携を順番に確認する形です。
移行方式を一括にするにしても段階的にするにしても、この承認ポイントが曖昧だと、切替後に「設定は入っているが運用は成立していない」状態が残ります。

移行前チェックリスト

設定・周辺の棚卸しテンプレート

移行前チェックで先に固めたいのは、「コード以外に何を運んでいるのか」の全体像です。
事故はたいてい、コード本体ではなく周辺設定の取りこぼしから起きます。
権限、ブランチ、タグ、履歴、README、.gitignore、Actions/CI、Webhook、Secrets、Packages、Pages、監査ログ、外部ツール連携までを、現状値と移行後目標の対比で並べると抜けが見えます。
GitHub Well-ArchitectedのChecklist for Repository Migrations – GitHub Well-ArchitectedやG移行前に対象を固定してから動くほうが、切替当日の判断が減ります。

既存リポジトリを取り込む場面では、README、.gitignore、License を移行先の『GitHub』作成画面で初期追加しないのが基本です。
ここで自動生成したファイルを先に入れると、既存履歴を push したときに無用な競合が起きます。
特に README は見た目にわかりやすいぶん「先に置いておこう」と判断されがちですが、実務では競合の火種になりやすい項目です。
README にはセットアップ手順、リリース手順、障害時対応、担当チームへの連絡先が書かれていることも多く、単なる説明ファイルではありません。
運用ドキュメントが別リポジトリやNotionConfluenceに逃げている場合も、参照先まで棚卸し対象に含めます。

.gitignore も同じです。
言語やツールに合っていない ignore を持ち込むと、ローカル依存ファイル、ビルド成果物、秘密情報を含む設定断片が混ざります。
Node.jsなら node_modules やビルド出力、Pythonなら仮想環境やキャッシュ、Terraform や各種 IDE 設定も見直し対象です。
「既存にあるから正しい」ではなく、現行の開発ツールに沿っているかを見ます。

権限まわりは、メンバー一覧だけでは足りません。
オーナー、メンバー、Team、外部コラボレータ、SSO の有無まで切り分けて、誰がどの入口からアクセスしているかを残す必要があります。
ブランチはデフォルトブランチ名、保護ルール、必須ステータスチェック、レビュー必須条件、force push の扱いを確認します。
タグとリリースは、単に存在するかではなく、どのタグがデプロイや『Sentry』のリリース追跡に使われているかまで見ておくと、切替後の「タグはあるのにリリースがつながらない」を避けられます。
履歴では Git LFS、Large Files、サブモジュールを見落とすと、コピーは終わっているのに中身が足りない状態になります。

下の表は、移行前の棚卸しにそのまま使える粒度でまとめたものです。
優先度は、5×5の一般的なリスクマトリクスの考え方に合わせて、移行影響が高いものから先に埋める前提で付けています。

CI/CD・Secrets・Webhookの要注意ポイント

CI/CD は、ワークフローが存在するだけでは移行完了になりません。
GitHub Actions なら、どのイベントで起動するか、どのランナーで動くか、schedule を使っているか、workflow_dispatch が運用フローに組み込まれているかを見ます。
schedule は高負荷帯で遅延することがあるので、定時実行を前提に業務手順が組まれているワークフローは、時刻そのものより「いつまでに終わる設計か」を一緒に棚卸ししたほうが実態に合います。
セルフホストランナーを使っているなら、ランナー名だけでなく、配置先、依存バイナリ、ネットワーク到達先も記録しておく必要があります。
ランナーは同時に1ジョブしか実行しない仕様なので、旧環境では回っていた順序が新環境で詰まることもあります。

GITHUB_TOKEN の権限設定も見落としやすい判断材料になります。
permissions キーを使ったワークフローでは、未指定の権限がアクセスなし扱いになります。
移行前にたまたま動いていた publish や release 作成が、移行後に contents: write や packages: write の不足で止まることがあります。
『GitLab CI』やBitbucket Pipelinesから持ってきた定義を置き換える場合は、ジョブ名やステップ名よりも、トリガー、認証、成果物の受け渡し、キャッシュ、デプロイ権限の4点を対応表で確認したほうが実務では抜けません。

Secrets は repo、organization、environment のどこに置かれているかで意味が変わります。
SENTRY_AUTH_TOKEN、クラウド資格情報、Slack 通知用トークン、Jira 用 API トークンなどを一括で見直すときは、値そのものより配置先と利用ジョブの組み合わせを先に固定すると整理できます。
環境保護ルールを使っている場合は、承認者、待機条件、対象ブランチも一緒に見ます。
ネイティブな有効期限設定の仕様が確認できないシークレットもあるので、実務では「いつ発行したか」「いつ rotate するか」を運用台帳で持っているチームのほうが切替後の混乱が少ない印象です。

Webhook は、設定一覧を見ただけでは足りません。
受け口の URL、イベント種別、認証方式、受信側の検証ロジック、失敗時の再送経路までが1セットです。
『GitHub』の Webhook は署名検証に X-Hub-Signature-256 を使えますし、ペイロードが 25 MB を超えるイベントは配信されません。
大きな push やタグ大量作成を伴う切替では、この制約が通知設計にそのまま効きます。
筆者自身、移行時に Webhook のシークレットだけ旧値のまま残してしまい、『Slack』通知が止まったことがありました。
設定画面では送信成功に見えていても、受け側が署名不一致で落としていたケースです。
それ以降は、チェックリストに受け側の検証用エンドポイントと再送テストを明示的に入れています。
これを加えてからは、「設定済みなのに届かない」を切替前に潰せるようになりました。

確認観点を CI/CD、Secrets、Webhook に絞ると、次の表の形でレビューしやすくなります。

GitLab CI/CD から GitHub Actions への移行 - GitHub ドキュメント

docs.github.com

Pages・Packages・監査ログ・外部連携の確認

アプリ本体の開発フローと比べて、Pages や Packages、監査ログ、外部ツール連携は後回しにされがちです。
ただ、ここが抜けると「デプロイは通るのに公開サイトが消える」「パッケージだけ pull できない」「監査証跡が切れる」といった、切替後に発覚しやすい障害になります。

Pages では、公開元ブランチ、ビルド方式、公開 URL、CNAME の有無、カスタムドメインの DNS 所有確認を棚卸しします。
特に旧リポジトリで gh-pages ブランチ運用をしていたのか、Actions ビルド経由で公開していたのかで、移行後の復元方法が変わります。
リポジトリの移譲や再作成では、Pages の公開設定やカスタムドメイン周辺に影響が出るため、GitHub ドキュメントのリポジトリを移譲する - GitHub ドキュメントで扱われている注意点と照らすと整理しやすくなります。

Packages は、何を publish しているかで確認項目が変わります。
npm、RubyGems、Maven、NuGet、Container registry など、利用しているレジストリをまず固定し、公開範囲が public か private か、権限がリポジトリ継承か個別設定か、GITHUB_TOKEN で publish しているのか別トークンかを見ます。
『GitHub Packages』は GITHUB_TOKEN で publish できるケースがありますが、レジストリや組織設定に依存するので、ワークフロー側の権限とパッケージ側の権限を対で見ないと、インストールだけ通って publish だけ落ちる形になります。

監査ログは、エンタープライズや組織管理の文脈で見逃しがちな一方、コンプライアンス要件に直結します。
誰が権限を変えたか、Webhook を更新したか、保護ブランチを緩めたかを追えないと、切替後の障害調査で「設定は変わったが誰が変えたか不明」という状態になります。
監査ログそのものの保持日数の数値はここでは置きませんが、監査対象イベントと確認責任者を移行計画の中で明示しておくと、単なる技術移行ではなく運用移行として整います。

外部ツール連携では、『Slack』Jira『Sentry』のように役割の違うサービスを一括で見ないことがコツです。
『Slack』は通知先とアプリ権限、Jiraは課題連携や webhook の受け口、『Sentry』はリリース追跡やコミット紐付けが中心です。
『Sentry』。
単に「連携あり」と書くと、どこで壊れても原因特定に時間がかかります。

この領域は、現状値と移行後目標を並べた表にしておくと、切替後レビューにも流用できます。

Packages は、何を publish しているかで確認項目が変わります。
npm、RubyGems、Maven、NuGet、Container registry など、利用しているレジストリをまず固定し、公開範囲や権限の設計を確認してください。
ワークフロー側の権限とパッケージ側の権限は別にチェックする必要があり、両者が噛み合わないと publish に失敗することがあります。

ここまで棚卸しできていると、移行当日に「コードはあるのに運用が空白」という事態を避けやすくなります。
見落としが出やすいのは、コードに見えない設定ほど責任者が曖昧な領域です。
権限は管理者、CI/CD は開発チーム、Pages は広報やフロント担当、Webhook は運用チーム、監査ログは情報システム部門、というように持ち主が分かれているなら、表のレビュー欄もその境界に合わせて持たせると、切替時の確認漏れが減ります。

GitHub Packages のドキュメント - GitHub ドキュメント

docs.github.com

段階的移行の進め方

フェーズ0: 現状棚卸しとゴール定義

段階的移行が向くのは、停止時間をまとめて取りにくく、関係者も設定項目も多いケースです。
たとえば『GitHub Actions』『Branch protection rules』『GitHub Secrets』『Webhook』、さらに『Slack』Jira『Sentry』まで絡むと、コード移送だけ先に終わっても運用は切り替わりません。
一括移行は日程を短く畳める反面、失敗時の影響が広く出ます。
並行運用は確実性を取りやすい反面、新旧を両方維持する負担が重くなります。
その中間にあるのが段階的移行で、影響範囲を区切りながら進められるのが利点です。
一方で、新旧連携の設計とフェーズごとの差分管理が増えるので、分割の仕方を誤ると運用の複雑さだけが残ります。

このフェーズの入力は、前段までで整理した対象資産の一覧、依存関係、停止制約、関係部門、監査や承認の要件です。
出力は、移行対象の確定版、移行しないものの明示、成功条件、失敗条件、責任分担表になります。
責任者はプロジェクトオーナーか移行責任者ですが、実務ではインフラ、開発、情報システム、業務部門の承認線までここで巻き取っておかないと後半で止まります。

私自身、フェーズ0で権限の所在を文章だけで持っていたときは、レビュー依頼先の認識が人によってずれていました。
そこで承認者、設定変更者、実作業者を結んだ「権限マップ」を図にしたところ、保護ブランチの変更承認と組織シークレットの更新承認が別ルートだと早い段階で見つかり、承認者不在で止まる筋を先に潰せました。
表だけでは見えない詰まり方があるので、このフェーズでは責任の線を絵で持つ価値があります。

完了基準は、何をいつどこまで切り替えるかを全員が同じ言葉で説明できることです。
チェック項目としては、対象リポジトリ、連携先、権限、Secrets、公開物、通知、監査対象イベントが漏れなく並んでいるか、成功判定が「移した」ではなく「運用が継続した」になっているかを見ます。
リスクの整理には、Asanaのリスクマトリクステンプレートのような5×5の整理枠を使うと、影響度と発生可能性を分けて扱えます。

フェーズ1: 対象分割とパイロット選定

棚卸しが終わったら、次は対象をどう分けるかです。
段階的移行の成否は、この分け方でほぼ決まります。
分割軸は、リポジトリ単位、機能単位、チーム単位、外部連携単位のどれかに寄せるのが基本です。
たとえば「主要アプリ本体」「共通ライブラリ」「CIテンプレート」「通知系連携」のように、依存の強いもの同士を同じ束にし、依存が薄いものは後ろに回します。

入力はフェーズ0で固めた対象一覧と依存関係図です。
出力は、移行ウェーブの一覧、各ウェーブの境界、同期が必要なデータや設定、パイロット候補です。
責任者は移行責任者に加えて、実際にそのリポジトリを使うチームリーダーが入るのが自然です。
技術的に移せても、利用側がその日から回せなければパイロットとして意味がありません。

パイロットに向くのは、影響が局所的で、失敗しても切り戻し経路が明快で、しかも本番に近い論点を含む対象です。
逆に、依存ゼロの小さな検証用リポジトリだけを選ぶと、本番でしか出ない問題を拾えません。
GitHub Well-Architectedの『Checklist for Repository Migrations – GitHub Well-Architected』でも、移行前後の確認観点を切り分けて扱っていますが、実務でも「小さすぎず、致命傷にもならない」対象を選ぶのが収まりの良い落としどころです。

完了基準は、どの順番で切り替えるかが時系列で並び、各ウェーブの入口条件が明記されていることです。
チェック項目としては、パイロットに本番相当の権限、CI、通知、レビュー導線が含まれているか、新旧の併存期間にどの情報を同期するかが書かれているか、パイロット成功後に横展開できる学びが取れるかを見ます。

フェーズ2-3: リハーサル1/2

段階的移行では、リハーサルを最低2回入れると精度が変わります。
1回では「通ったかどうか」しか見えず、改善が本当に効いたかの検証まで届きません。
実務では複数回のリハーサルが望ましいという知見があり、『Qiitaの移行計画のポイント』のような現場知見でも、制約条件の整理と手順の反復が軸になっています。

リハーサル1回目の入力は、移行計画、ドラフト手順書、検証項目、パイロット環境です。
ここでの目的は、手順の穴出しです。
コマンドの抜け、権限不足、通知先の漏れ、保護ブランチ解除の承認待ち、Secrets 名の不一致、Webhook の向き先ミスなど、机上で見えない詰まりを洗い出します。
責任者は作業責任者ですが、判定には利用部門も同席した方がよく、技術的成功と業務的成功を分けて記録します。
完了基準は、失敗点とその原因がすべて手順書に反映されることです。

リハーサル2回目では、1回目で見つかった穴を埋めた結果、停止時間が短くなったか、確認作業が前倒しできたか、判断待ちが減ったかを検証します。
筆者の事例では、承認順と検証順を入れ替え、事前に確認できる設定を切替前日に寄せたことで停止時間が短くなったと感じています（対象リポジトリの規模や関与者数など環境に依存するため、必ず同等の効果が得られるとは限りません）。
1回目は問題発見の回、2回目は改善確認の回として性格を分けると、リハーサルが単なる反復になりません。

このフェーズのチェック項目は、開始条件が揃わないまま着手していないか、手順ごとに責任者が一意か、検証がUI確認だけに寄っていないか、切り戻しの模擬実行まで含めたかです。
完了基準は、1回目で見つかった課題に対して是正策が入り、2回目でその是正が有効だと確認できることです。

移行計画のポイント - Qiita

今回はみんなが大好きな「移行」について、 ここ3年間で大小4つのプロジェクトで本番移行の計画・推進のご支援を行った経験から、 その計画を立てる上でのポイントをいくつか共有したいと思います。 前提知識 システム開発における移行とは 簡単に言う

qiita.com

フェーズ4: 本番移行

本番移行は、段階的移行の中でもっとも短く、もっとも判断密度が高い時間帯です。
入力は、承認済みの移行計画書、確定版手順書、リハーサル結果、切り戻し条件、連絡網です。
出力は、対象ウェーブの切替完了、証跡、未解決課題一覧になります。
責任者は全体統括、実作業者、判定者を分けます。
同じ人が作業と判定を兼ねると、止めるべき場面で止めにくくなるからです。

本番では、時系列のToDoを曖昧にしないことが効きます。
切替前の最終バックアップ、変更凍結、権限確認、ミラーまたは移送、CI有効化、保護ブランチ反映、Webhook 切替、通知確認、利用部門による受入確認という順番を固定し、その都度ゲートを通します。
たとえば『GitHub Actions』は permissions を明示したとき未指定権限がアクセスなしになる仕様なので、移行元で暗黙に動いていたワークフローが移行先で止まる場面があります。
本番当日に初見で当たると切替時間を消耗するため、ゲートごとに「想定通りか」「次へ進むか」「切り戻すか」を判定します。

完了基準は、対象ウェーブに含めた機能が新環境で稼働し、利用者が新しい導線で作業を継続できることです。
チェック項目としては、対象ブランチへの push 制御、レビュー要件、Secrets 参照、主要ワークフロー、通知、外部連携、監査可能性が揃っているかを確認します。

フェーズ5: 検証と是正

本番後の検証は、移行作業の後始末ではなく、本番移行の一部です。
入力は本番時の実行記録、ログ、利用部門からの一次フィードバック、監査対象イベントです。
出力は、検証結果、未達項目、是正計画、恒久対応の優先順位になります。
責任者は運用責任者と移行責任者の共同管理が合います。
切替そのものは終わっていても、是正は運用に組み込まれるからです。

ここでは、想定した成功条件を実データで照合します。
PR 作成からレビュー、マージ、CI、デプロイ、通知、障害検知まで一連の流れが新環境で閉じているかを見ると、単発の疎通確認より精度が上がります。
Webhook を使う連携では、『GitHub』側のペイロード上限が 25 MB なので、大きなイベントを契機にした仕組みは本番直後にログまで追った方が流れを確認しやすくなります。
検証の単位を「画面で設定が見える」ではなく「運用シナリオが通る」に置くのが、このフェーズの肝です。

完了基準は、未達がある場合でも、影響範囲と恒久対応の日付・担当が決まっていることです。
チェック項目には、運用フローの通し確認、監査証跡の取得、残課題の分類、旧環境を残す理由の有無を含めます。

切り戻し条件・判定ゲート

段階的移行で安心材料になるのは、「問題が起きたら戻す」ではなく、「どの条件に触れたら戻す」を事前に固定しておける点です。
ここが曖昧だと、現場は止めるべきか進めるべきかで迷い、結果として障害を抱えたまま先へ進みます。

切り戻し条件は、技術条件、業務条件、時間条件の3つに分けると整理しやすくなります。
技術条件は、主要CIが通らない、Secrets 参照に失敗する、Webhook 通知が届かない、保護ブランチの期待動作が崩れるといったものです。
業務条件は、レビューやリリースの業務が当日中に再開できない、監査に必要な変更記録が追えない、承認者が実施不能と判断した状態です。
時間条件は、予定停止枠の中で次のゲートに達しない場合のように、時計で区切る条件です。

判定ゲートは、開始前、データ移送後、設定反映後、運用シナリオ確認後のように置くと、進退を決める場所が明確になります。
各ゲートでは、判定者、必要な証跡、許容条件、不許可時のアクションを1行で書ける形にしておくと、本番の会話が短くなります。
段階的移行のメリットは、切り戻し範囲をフェーズ単位に閉じ込められることです。
デメリットは、ゲートが甘いと問題を次のウェーブへ持ち越してしまう点にあります。

移行計画書 vs 手順書

実務で混同されやすいのが、移行計画書と移行手順書です。
この2つは役割が違います。
移行計画書は「なぜ、どこまで、誰の責任で、いつ、どういう方針で移すのか」を定義する文書です。
目的、範囲、対象外、体制、スケジュール、判定ゲート、切り戻し方針、連絡体制が中心になります。
一方、移行手順書は「何時に、誰が、どの画面またはコマンドで、何を実施し、どう検証するか」を刻んだ実行文書です。

たとえば計画書には「第1ウェーブで主要リポジトリを移し、障害時は旧運用へ切り戻す」と書きます。
手順書には「00:10 に書き込み凍結、00:15 にミラー取得、00:25 に新環境へ反映、00:35 に Webhook 疎通確認、00:45 に『Slack』通知確認」のように、時刻、担当、操作、確認方法を書きます。
この分離に近い整理がされていますが、現場では両方を一つに押し込むほど抜けが増えます。
計画書は判断のための文書、手順書は実行のための文書として分けた方が、承認も作業も流れます。

段階的移行を選ぶチームでは、計画書がウェーブ管理の土台になり、手順書が各ウェーブの再現性を支えます。
一括移行では手順書の出来が直撃し、並行運用では計画書の範囲定義と終了条件が直撃します。
段階的移行はその中間に見えて、実は両方の文書品質がそのまま成果に出る方式です。
ここが整っていると、どの方式を選んでも判断の粒度が揃います。

実践例: 既存ローカルプロジェクトをGitHub管理へ移す

既存のローカルプロジェクトを『GitHub』管理へ載せる流れは、実際にはそこまで長くありません。
つまずきやすいのはコマンドの数より、どの時点で何を作るかの順番です。
ここでは、いま手元にあるフォルダをそのまま Git 管理にし、履歴を壊さず『GitHub』へ公開する最小手順を、確認ポイント込みで通せる形に絞って整理します。

ステップ1: 初期化と.ignore

まずは既存フォルダを Git の管理対象にします。対象プロジェクトのルートへ移動して、git init を実行します。

cd /path/to/your-project
git init
git branch -M main

git init を打った時点で、そのフォルダに .git ディレクトリが作られ、Git が履歴を持てる状態になります。
ここであわせて git branch -M main を入れておくと、初回 push のブランチ名を main に統一できます。
古い環境では master で始まることがあるので、最初にそろえておく方が後工程で迷いません。

次に .gitignore を作ります。
ここで除外漏れがあると、node_modules、ビルド成果物、ログ、ローカル設定、秘密情報まで初回コミットに入ってしまいます。
最初の1回目で混ざると、あとから履歴ごと掃除する話になりやすいので、ここは先に止めておく方が安全です。

たとえばNode.js系なら、こういう最小形から始められます。

node_modules/
dist/
build/
.env
.DS_Store
*.log

Python なら __pycache__/ や .venv/、Java なら target/、IDE を使っているなら .idea/ や .vscode/ の扱いもこの段階で決めます。
作成後は git status で追跡対象を確認します。

git status

ここで見るポイントは、上げるつもりのないファイルが Untracked files に出ていないかです。
もし .env や生成物が並んでいたら、初回コミットの前に .gitignore を足します。
初手の git status を丁寧に見るだけで、後からの手戻りがだいぶ減ります。

ステップ2: 初回コミットと空リポジトリ作成

追跡対象が整ったら、初回コミットを切ります。

git add .
git commit -m "Initial commit"

コミット後は、履歴が1本できていることを確認します。

git log --oneline -1

この段階でローカル側の準備は完了です。
次に『GitHub』で新しいリポジトリを作りますが、ここで事故が起きやすいポイントがあります。
README、License、.gitignore を作成画面で追加しないことです。
既存ローカルプロジェクトをそのまま push する場合、移行先は空リポジトリにしておくのが基本です。

筆者も以前、作成画面で README を追加したあと、手元のプロジェクトにも README があり、最初の統合で余計な競合を踏みました。
内容は小さな差分でも、初回 push の時点で「ローカルだけの履歴」と「リモートだけの履歴」が分かれてしまい、単純な導入手順ではなくなります。
それ以来、既存フォルダを載せるときは必ず空リポジトリへ push する運用にそろえています。
GitHub DocsのCreating a new 。

リポジトリ作成画面では、名前だけ決めて作れば十分です。
公開・非公開の選択は用途次第ですが、GitHub Freeでも public と private の両方のリポジトリを作れます。
ここで必要なのは、まだ何もコミットがない空の箱を用意することです。

ステップ3: remote追加とpush

空リポジトリができたら、ローカルから origin を追加して push します。
『GitHub』のリポジトリ画面に表示される URL を使い、HTTPS か SSH のどちらかで設定します。

git remote add origin（初回実行）
git remote -v

git remote -v で origin の fetch/push URL が期待通りに出れば接続先は設定完了です。そのまま初回 push を行います。

git push -u origin main

-u を付けると、以後の git push や git pull で追跡先ブランチが省略できるようになります。
push 後は『GitHub』の画面を更新し、ファイル一覧、コミット履歴、ブランチ名が main になっているかを見ます。
ローカルでも確認できます。

git branch
git status

git branch git status git log --oneline --decorate -1

`git status` が clean で、現在ブランチが `main`、最新コミットに `origin/main` が付いていれば、基本の接続は通っています。もし `Untracked files` や予期しないファイルが出ている場合は、初回コミット前に `.gitignore` を修正して再確認してください。
タグを使う運用なら、この時点でタグも上げられます。単発なら次の形です。

git tag v1.0.0 git push origin v1.0.0

既存プロジェクトにすでにローカルタグがあるなら、まとめて送るにはこうします。

git push origin --tags

タグを push していないと、コード本体だけ移ってリリース起点だけ欠ける状態になります。アーカイブ単位や配布版単位でタグを使っていたプロジェクトでは、ここを忘れると後で履歴の見え方が変わります。

もし誤って『GitHub』側で README などを追加してしまい、リモートに先行コミットができていた場合は、そのまま強引に押し込むより、履歴をどう合わせるかを先に決めた方が整合が取りやすくなります。ただし、最初から空リポジトリで始めればこの分岐自体を踏まずに済みます。導入パターンを再現可能にするという意味でも、ここは手順の統一効果が大きいところです。

### 完了チェック

push が通ったら、単にファイルが見えたかだけで終わらせず、運用の土台まで軽く整えておくと次の作業が滑らかになります。GitHub Well-ArchitectedのChecklist for Repository Migrationsが触れている通り、移した後の既定値と保護設定まで見ておくと、あとから「置いただけ」のリポジトリになりません。

確認対象は次のあたりです（重要点のみを列挙しています）。
1. 『GitHub』の default branch が `main` になっていること
2. 必要に応じて `main` に branch protection rules が設定され、直接 push が制限されていること
3. 『GitHub Actions』を使う場合、push を契機に CI が起動することを確認
4. README の内容、リポジトリ説明、公開範囲が現状に合致していること
5. リリース運用がある場合、タグが移行先に揃っていること

『GitHub Actions』は `push` をトリガーにできるので、ワークフローファイルをすでに含んでいるプロジェクトなら、初回 push の直後に CI が走ることがあります。逆に、動く前提だったのに何も始まらないなら、`.github/workflows/` の配置やトリガー条件の確認に進みます。保護ルールについても、コードを置いた直後はまだ素通しの状態なので、レビュー必須やステータスチェック必須を入れるかどうかで、その後の運用の質が変わります。

この一連の流れは単純に見えて、順番を崩すと無駄な統合作業が増えます。ローカルで Git 管理化し、`.gitignore` を整え、初回コミットを作り、README なしの空リポジトリへ `main` を push する。この型にそろえるだけで、既存ローカルプロジェクトの『GitHub』導入は安定します。

## 実践例: 既存リモートリポジトリを別環境へ移行する

### mirror cloneと通常cloneの違い

既存のリモートリポジトリを別環境へ移すときは、日常作業で使う `git clone` ではなく、移行専用の `git clone --mirror` を使うのが基本です。通常の clone は作業ツリー付きで取得し、主に現在見えているブランチで開発する前提です。一方で `--mirror` はベアリポジトリとして取得し、ブランチ、タグ、リモート追跡参照を含む refs を丸ごと持っていくため、履歴をそのまま別のホスティング先へ再現する用途に向いています。AWS CodeCommitの移行例でもこの流れが案内されており、移行専用コピーとして扱う考え方は共通です。

ここで混同しやすいのが、前のセクションで扱った「ローカルの既存フォルダを新しく Git 管理化する」流れとの違いです。ローカルプロジェクトを初めて管理対象に入れる場合は、`git init` でリポジトリを作り、`.gitignore` を整え、初回コミットを作ってから、README などを追加していない空リポジトリへ `remote` を追加し、push します。『GitHub』の新規リポジトリ作成画面で最初から README を足さないのは、リモート側に先行コミットを作らず、履歴の起点をローカルの初回コミットにそろえるためです。これはGitHub DocsのCreating a new repositoryでも既存内容を push する前提として自然な流れになっています。

たとえば、まだ Git 管理されていない既存フォルダを『GitHub』に載せる最小手順はこうです。

cd your-project git init printf "node_modules/\n.env\n.DS_Store\n" > .gitignore git add . git commit -m "Initial commit" git remote add origin（移行先で実行） git push -u origin main

これに対して、すでに別のリモートにあるリポジトリを移す場合は、初回コミットを新たに作るのではなく、既存履歴を保ったまま写します。つまり `git init` と初回コミットの出番ではなく、`git clone --mirror` と `git push --mirror` の出番です。同じ「移す」でも、片方は新規導入、片方は履歴の複製です。

移行元が `、移行先が『GitHub』の ` だとすると、入口は次のようになります。

git clone --mirror cd project.git git remote -v

この時点でできる `project.git` はベアなミラーコピーなので、普段の編集、コミット、レビュー作業には使いません。移行作業専用の一時ディレクトリと割り切ると、通常開発用の clone と混線しません。

### mirror pushの安全な実行手順

ミラーコピーを作ったら、push 先を新環境へ向けて `git push --mirror` を実行します。移行先では空リポジトリを先に作成しておき、README や `.gitignore` やライセンスを自動追加しない状態にしておくと、refs の上書きが素直に進みます。ここは前の導入パターンと同じで、移行先に余計な初期履歴を作らないことが衝突回避につながります。

# ミラー取得（ を実際のリポジトリ URL に置き換えて実行） git clone --mirror cd project.git git remote -v

git remote set-url --push origin
git push --mirror

origin をそのまま使うと移行元の fetch URL を保持したまま push 先だけ差し替えられるので、元の参照先を見失いにくくなります。
push 先 URL を明示しておくことも事故防止に効きます。
別名で持ちたいなら次のようにしても構いません。

git remote rename origin old-origin
git remote add origin（確認用）
git remote -v
git push --mirror origin

# push 先を新環境に差し替える例（確認用プレースホルダを使用）
git remote rename origin old-origin
git remote add origin <NEW_REMOTE_URL>  # <NEW_REMOTE_URL> を移行先の URL に置き換える
git remote -v
git push --mirror origin

git show-ref
git show-ref --tags
git ls-remote

移行後の確認項目は、画面と CLI の両方でそろえると取りこぼしが減ります。

1. 主要ブランチが想定どおり存在することを確認する
2. refs/tags に必要なタグがそろっていることを確認する
3. 既定ブランチが意図した名前になっていることを確認する
4. リリース起点にしているタグから過去コミットをたどれることを確認する
5. Pull Request が Git オブジェクトではなくホスティング側の機能で管理される点を踏まえ、別途移行対象かどうかを整理済みであることを確認する

ここでひっかかりやすいのが Pull Request です。
git push --mirror で移るのは Git の履歴や refs であって、レビュー会話や承認状態そのものではありません。
『GitHub』内のリポジトリ移譲とは違い、別サービス間の移行では PR の扱いを Git の一部だと思わない方が整理できます。
タグ、ブランチ、リリース運用の起点は mirror で寄せられても、レビューの文脈は別の棚にある、という理解の方が実務に合います。

Pages/カスタムドメインの注意点

リポジトリの置き場所を変えるときはGitHub Pagesとカスタムドメインの扱いを切り離して考えた方が安全です。
とくに独自ドメインを使っていたリポジトリでは、移譲や移行のあとに古い設定が残ると、意図しない公開状態やドメイン乗っ取りの余地を作ります。

Pages を使っている場合は、リポジトリ本体の mirror 移行だけで終わりません。
公開元ブランチやディレクトリ、CNAME、DNS レコードの向き先まで含めて見直す必要があります。
移譲機能を使う場面でも、カスタムドメイン設定の削除や更新を先に整理しておかないと、旧リポジトリと新リポジトリのどちらが公開責任を持つのか曖昧になります。

特に押さえたいのは次の点です。

• 旧環境で使っていた CNAME ファイルの有無
• GitHub Pagesの公開設定が新しいリポジトリ側で再現されているか確認する
• カスタムドメインの DNS が旧環境を向いたままになっていないか確認する
• 旧リポジトリ側に残した Pages 設定を削除済みか

ドメイン周りは Git の履歴とは別管理なので、mirror push が成功しても自然には片付きません。
私はここを「リポジトリ移行の付随設定」ではなく、「公開経路の切替」として別タスクに分ける方が事故を減らせると感じています。
コードの移行と DNS の切替を同じ頭で処理すると、どちらかの確認が薄くなります。

移行後の通常cloneと周知

mirror 用に作ったベアリポジトリは、移行完了後の日常作業に流用しません。
新環境で正しく履歴が見えていても、そのコピーはあくまで搬送用です。
実開発は移行先から通常の git clone をやり直し、チーム全員の作業起点を新 URL にそろえます。

cd project
git remote -v
git branch -a
git tag

既存メンバーが手元の clone を使い続ける場合は、origin の URL だけ切り替える方法もあります。

git remote set-url origin
git remote -v
git fetch --all --tags

この切替と合わせて、チーム運用では周辺接続の更新も発生します。
コードが見えているのに CI だけ動かない、通知だけ旧環境へ飛ぶ、というズレはここで起きます。
『GitHub Actions』を使うなら、Secrets、GITHUB_TOKEN 前提の権限設計、外部サービス連携を新環境側へ寄せる必要がありますし、Webhook を使うなら配送先 URL や署名シークレットも再設定対象です。

周知の内容は、開発者向けと運用向けで分けると混線しません。
開発者には新しい clone URL、既存 clone の remote 切替方法、既定ブランチ名を伝えます。
運用側には CI 接続、Packages、Pages、Webhook、外部連携トークンの更新範囲を渡します。
GitHub Well-Architectedの移行チェックリストが役立つのはこの段階で、コード移行後に残る「Git ではない設定」を一覧で扱えるからです。

移行元をしばらく参照専用にして、新環境へ一本化するまでの短い並行期間を設ける運用もありますが、その間でも日常の commit と merge は新環境へ集めた方が履歴の分岐を防げます。
mirror 用コピーで運用を続けないこと、新環境から通常 clone を取り直すこと、remote の切替先をチームで統一すること。
この三つをそろえると、既存リモートの移行が単なる複製で終わらず、実運用まで自然につながります。

移行時のリスク管理と切り戻し

5×5リスクマトリクスの作り方

移行計画で最初に固めたいのは、「どの失敗から先に潰すか」を決めることです。
影響度は「止まる範囲」、発生確率は「その切替で起きる見込み」と定義すると、各リスクに対する優先度が見えやすくなります。
こうして点数化すると、感覚的な「怖そう」という議論を具体的な対策へつなげられます。

ここでの「権限過大」は、移行時に『GitHub Actions』の GITHUB_TOKEN や個人トークンを旧環境のまま流用し、必要以上の権限で通してしまうケースです。
GitHub Docsにある通り、permissions キーを明示した場合、未指定の許可はアクセスなしになります。
移行直後の混乱を避けるために広い権限を与えるのではなく、必要なジョブに必要な権限だけ戻す方が、事故の範囲を抑えられます。

Webhook は「つながっている前提」で見落とされがちです。
GitHub Webhooksはペイロード上限が 25 MB で、それを超えるイベントは配信されません。
移行日に大量 push や設定変更が重なると、受信側の障害と混同しやすいので、配送失敗を単なる一時エラーとして扱わず、独立したリスクとして置いておく方が混乱を防げます。
『Slack』通知やJira Cloud連携、『Sentry』のリリース通知まで含めると、Webhook 停止の影響は見た目以上に広がります。

私は移行計画書で「本番デプロイが落ちたら 5 分で旧環境へ戻す」と先に決め、その前提でマトリクスを作りました。
そのとき優先度 1 位に置いたのが CI 失敗で、監視対象もまずそこに寄せました。
実際に障害が起きたとき、新環境のデプロイワークフロー失敗を最初に検知できたことで、判断がぶれず、旧環境への切替と復旧連絡まで含めて 10 分で収まりました。
切り戻し計画は保険というより、優先順位を数字で固定するための道具です。

切り戻し条件・判断ゲート・復旧手順

切り戻しが機能するかどうかは、手順書の厚さではなく、どの状態になったら戻すのかが先に決まっているかで決まります。
移行当日に議論が始まる項目は、たいてい戻すべきタイミングを逃します。
そこで、切替前に判断ゲートを置き、各ゲートを通過できなければ旧環境へスイッチバックする形にしておくと、判断者も実行者も迷いません。

定義しておきたい切り戻し条件は、少なくとも CI 成功率、重要ワークフローの稼働、監査項目の合格、停止時間の超過です。
CI 成功率は全ワークフローではなく、本番系に直結するジョブを対象にします。
たとえば build、test、deploy、release、通知のように、止まると業務影響が出る流れだけを「重要ワークフロー」に固定しておく方が運用に合います。
監査項目には、保護ブランチ、レビュー必須設定、permissions の最小権限、Secrets の接続先、公開経路の設定を含めると、見た目だけ成功している状態を避けられます。
判定ゲートは、開始前、データ移送後、設定反映後、運用シナリオ確認後のように配置すると、進退を決める場所が明確になります。
各ゲートでは、判定者、必要な証跡、許容条件、不許可時のアクションを1行で書ける形にしておくと、本番の判断が速くなります。
判断ゲートは、次のように文章で残すと現場で使えます。

1. 主要ワークフローが新環境で連続して成功していることを確認する
2. 本番デプロイに使う Secrets と環境変数が意図した参照先になっていることを確認する
3. 保護ブランチとレビュー条件が移行前の運用ルールを満たしていることを確認する
4. 通知と外部連携が新環境から発火していることを確認する
5. 計画した停止時間を超えた場合は、到達率に関係なく旧環境へ戻すこととする

この「停止時間を超えたら戻す」は、感情を排除するための条件です。
あと少しで終わりそうに見える局面ほど、障害は長引きます。
移行作業は達成率ではなく、業務再開時刻で評価した方が実態に合います。

切り戻し手順も、抽象語ではなく実行単位まで落とします。
リポジトリ移行なら、旧 origin へ向けた remote の戻し、CI の既定ブランチ設定の差し戻し、Webhook 配送先 URL の復元、Pages の公開元設定の戻し、必要なら DNS の向き先の復旧まで書いておきます。
Git の操作だけで済むと思っていると、連携面が宙に浮きます。

たとえばコマンドの戻し方は、開発者向けと運用向けで分けておくと混線しません。

git remote set-url origin
git remote -v
git fetch --all --tags

新環境の mirror 用作業コピーを使っていた場合は、旧環境へ戻す側の参照先が明示されていないと、復旧中にさらに push 先を誤ります。
復旧手順書には、どの URL に戻すか、どの設定画面で何を戻すか、誰が実行して誰が判定するかまで含めます。
判定者と作業者を分ける運用にしておくと、「実行した本人が大丈夫と言っている」状態を避けられます。

停止時間・連絡体制・検証項目

移行の失敗は、技術的な不具合そのものより、停止時間と連絡の混線で被害が広がることが多いです。
そのため、本番窓の定義、変更フリーズの開始と解除、誰にいつ連絡するかを、作業項目と同じ粒度で置いておく必要があります。
GitHub Well-Architectedの『Checklist for Repository Migrations』が役立つのも、コード移行だけでなく周辺設定と関係者整理を同じ面で見られるからです。

停止時間の計画では、少なくとも「フリーズ開始」「切替開始」「判定時刻」「フリーズ解除」を分けます。
フリーズ開始以降は merge や release を止め、差分が増えない状態で切替に入ります。
解除は単に push できる状態ではなく、機能、権限、通知、デプロイの検証が通ったあとに置きます。
ここを曖昧にすると、確認中に通常運用が再開して、旧新どちらを正とするのか崩れます。

関係者連絡は、相手別にメッセージの粒度を変えます。
開発者には clone URL、既定ブランチ、CI の見方、フリーズ中の禁止操作を伝え、運用担当には Secrets、Webhook、Packages、Pages、監査ログ確認の担当範囲を明示します。
事業側やサポート窓口が関わるなら、停止時間と復旧見込みだけを先に渡し、技術詳細を混ぜない方が行き違いを減らせます。
チャネルも、即時連絡は『Slack』、記録はチケットや議事ログ、最終判定は責任者承認というように役割を分けると、あとから追跡できます。

検証項目は「全部見る」ではなく、移行で壊れやすい境界に絞ります。最低限のチェックリストなら、次の 4 群で足ります。

• 機能: clone、push、pull request、マージ、タグ作成、リリース作成

この並びにしておくと、アプリ本体の挙動だけでなく、開発フローと運用フローの断線も拾えます。
とくに通知とデプロイは「成功したように見える失敗」が出やすいので、ジョブが green になったことと、実際に通知や公開が届いたことを分けて確認した方が事故を防げます。

移行当日は、検証項目を上から順に消していくより、切り戻し条件に直結するものから先に潰す流れが合っています。
私が CI 失敗を最上位に置いたのもそのためで、本番窓では build と deploy が通らない時点で他の合格に意味がなくなるからです。
停止時間、関係者連絡、検証項目を同じ紙幅で扱うと、技術の問題を運用で長引かせない計画になります。

移行後にやること

CI/CD・保護ルールの再確認

移行直後は、コードが見えていることより、自動化が以前と同じ意味で動いているかを先に確かめる段階です。
『GitHub Actions』は push、pull_request、workflow_dispatch、schedule など複数のトリガーで動きますが、移行後に詰まりやすいのはワークフロー本体よりも、Secrets、Environment、GITHUB_TOKEN の権限、外部サービス向けトークンの結線です。
GitHub Docsの『GitHub Actions』と『GITHUB_TOKEN』の説明にある通り、permissions キーを明示した場合、未指定の権限はアクセスなしとして扱われます。
移行前はたまたま通っていた publish や release 作成が、移行後に急に失敗するのはここが原因であることが多いです。

そのため、CI/CD は設定を見比べるだけで終わらせず、代表的なワークフローを強制再実行して結果を見るところまで進めます。
手動実行できるものは workflow_dispatch で流し、push 起点のものはテスト用ブランチから実際にトリガーします。
定期実行ジョブも、前述の通り schedule は混雑時に遅延することがあるので、移行直後の確認では待つより手動実行の経路を優先した方が実態をつかめます。
セルフホステッドランナーを使っているなら、ランナーが新しいリポジトリや組織に正しくひも付いているか、ジョブが拾われるかも合わせて見ます。
ランナーは同時に1ジョブずつ処理する仕様なので、キュー詰まりを移行不具合と誤認しない切り分けも必要です。

保護ルールも、画面上で設定が入っているだけでは足りません。
『GitHub』のブランチ保護では、レビュー必須、必須ステータスチェック、会話解決、線形履歴、署名済みコミット、プッシュ権限制限などを組み合わせられますが、移行後はどのチェック名が必須扱いになっているかがずれていることがあります。
CI のジョブ名を変えたのに保護ルールだけ旧名のままだと、永遠に merge できない状態になります。
逆に、必須チェックの設定漏れがあると、壊れたまま main に入ります。
ここはテスト用の pull request を一本作って、レビュー、ステータスチェック、マージ条件が想定通りに効くかを通しで見る方が早いです。

Webhook の再送テストも、この段階で一緒に片づけます。
GitHub Webhooksでは署名検証に X-Hub-Signature-256 を使う構成が推奨され、ペイロードは 25 MB を超えると配信されません。
通知先が『Slack』でも『Sentry』でも、受信側で署名や URL を持ち替えていると、移行後に green のまま外へ何も届かないことがあります。
私は Webhook の設定画面で配信履歴を眺めるだけで済ませず、実際に再送をかけて、受信側ログで delivery 単位に照合するところまでを「移行完了」の条件にしています。

ドキュメント更新とチーム教育

移行は技術作業に見えて、運用の文章を書き換えるところで組織への定着が決まります。
README だけ新しくしても、レビュー方針や権限表や障害時の連絡先が旧環境のままだと、現場は古いルールに戻ります。
私が更新対象としていつも先に洗うのは、README、運用ルール、ブランチ戦略、権限表、CI/CD の実行条件、移行記録です。
とくに権限表は、誰が admin を持つのか、誰が保護ブランチに例外 push できるのか、Secrets の更新権限を誰に持たせるのかまで書かれていないと、属人的な口頭運用に戻ります。

README には、clone URL や既定ブランチの説明だけでなく、開発開始の最短手順を書きます。
運用ルールには、pull request の出し方、レビューの観点、緊急時のマージ手順、ラベル運用、Issue テンプレートの使い分けを書きます。
Issue テンプレートや pull request テンプレートも、移行先の運用に合わせて文面を整えないと、旧サービス前提の項目が残り続けます。
「どこに書いてあるか」が曖昧だと、ルールは存在していても使われません。

チーム教育では、資料配布だけでは定着しません。
私は移行後に短い説明会を入れるより、実際の pull request を題材に新ルールで一度回す方が効くと感じています。
新しいブランチ戦略でどこから切るのか、レビューで何を必須とするのか、CI が落ちたとき誰が直すのか、Issue テンプレートのどこまで埋めるのかを、その場で一度なぞるだけで迷いが減ります。
移行後に2週間の「定着スプリント」を置き、毎朝10分のスタンドアップで小さな不具合や運用のひっかかりをその日のうちに掃除したことがありますが、この期間を挟むと「新ルールを知っている」状態から「新ルールで仕事を進められる」状態へ変わります。
結局、定着したのは立派な移行計画書より、毎朝出てきた細かな詰まりを放置しなかったことでした。

教育内容は抽象化しすぎない方が伝わります。
たとえば「レビューを厳格化する」ではなく、「main への直接 push はしない」「会話が unresolved のまま merge しない」「必須チェックが通る前に approve を終えない」といった実際の操作単位でそろえると、解釈の幅が狭まります。
移行記録にも、何をいつ切り替えたかだけでなく、どの設定でつまずいたか、どこを手修正したかを残しておくと、次の repo 展開で同じミスを踏みにくくなります。

定着確認とメトリクス

移行後に本当に見るべきなのは、切替当日の成功判定より、その後の運用が滑らかに回るかです。
ここで有効なのが、短期間でもよいので定着確認の期間を明示的に置くことです。
私の現場では、移行後の2週間を定着スプリントとして扱い、毎朝10分だけ集まって、前日までに出た小さな不具合を確認して片づけていました。
通知が遅れた、保護ルールで想定外のブロックが起きた、Secrets の参照先が誤っていた、といった一つひとつは小粒でも、放置すると「この新運用は面倒だ」という印象だけが残ります。
逆に、その場で直し続けると運用ルールが自然に組織へ染み込みます。

監視期間に追う指標も、抽象的な満足度ではなく、日々の流れに直結するものに絞った方が判断しやすくなります。
実務では、失敗ジョブ率、デプロイ完了までの所要時間、通知の遅延や未達の3つを見るだけでも十分です。
Actions のジョブ一覧、デプロイ履歴、通知先の受信ログを並べると、どこで詰まっているか見えます。
定期ジョブが絡む場合は、schedule 実行の遅れも観察対象に入ります。
毎時きっかりで設計していた運用は、移行後に数分の遅れが積み上がるだけで現場の感覚が変わるためです。

ここでのポイントは、異常をその場しのぎで潰して終えないことです。
定着期間に見つかった項目は、恒久対応と運用回避策を分けてバックログ化します。
たとえば、GITHUB_TOKEN の権限不足で一部ジョブが失敗したなら、その場では必要権限を足して復旧しつつ、後続タスクとして権限の最小化と再棚卸しを切ります。
Webhook 通知の遅延なら、受信側の再送処理や監視の有無を別タスクに分けます。
改善を backlog に落とすことで、「移行後の雑務」ではなく、運用基盤の整備として扱えるようになります。

定着確認の観点では、数字と同じくらい、問い合わせの質も手がかりになります。
初週は「どこに push するのか」「なぜ merge できないのか」といった入口の質問が出て、数日後には「この例外運用は誰が承認するのか」という制度面の質問に変わります。
この変化が出てくると、チームは新しい環境そのものではなく、新しいルールの運用へ関心を移し始めています。
技術移行が組織運用へ切り替わったサインです。

Pages/Packages/監査ログの最終点検

本体のコードと CI が安定しても、周辺機能の点検が抜けると移行は締まりません。
まずGitHub Pagesを使っているなら、公開元ブランチやディレクトリだけでなく、カスタムドメインの DNS と証明書状態まで通しで見ます。
表示できるかどうかだけではなく、期待したドメインで開き、証明書が正常に配布され、旧環境へ向く設定が残っていないことまで確認できて、はじめて移行後の公開基盤として落ち着きます。

『GitHub Packages』は、設定画面を移しただけでは不十分で、pull と push の両方を実行して挙動を見ます。
『GitHub Packages』は npm、Maven、NuGet、コンテナレジストリなどを扱えますが、publish できるかと install できるかは別問題です。
Actions から GITHUB_TOKEN で publish できる構成でも、パッケージ権限の継承やレジストリ設定が噛み合っていないと、取得側で失敗します。
私がよくやるのは、CI からの publish テストと、別のクリーンな環境からの install テストをセットにするやり方です。
公開経路だけ通っていて、利用経路が詰まる事故を防げます。

監査ログも見逃せません。
とくに組織単位で権限変更や Secrets 更新、保護ルール変更を伴った移行では、何がいつ誰によって変更されたかを後から追える状態にしておく必要があります。
『GitHub Enterprise』系の機能を使っている環境では、監査ログの取得と保管の流れまで含めて移行後作業に入れておくと、後日レビューや内部監査で慌てません。
ここは「必要になったら見に行く」ではなく、移行当日から定着期間にかけてのログをひとかたまりで残しておくと、障害調査でも効きます。

Pages、Packages、監査ログは、どれも主役ではありませんが、抜けたときの痛みが遅れて出ます。
移行後の仕上げは、派手な障害の有無ではなく、公開、配布、追跡の3本が静かに成立しているかで見た方が実態に近いです。

付録: サンプル資料とテンプレート

実務でテンプレートを作るときは、最初から列を増やしすぎない方が運用が安定します。
ここに載せる雛形は、私が現場で回しているチェックシートをもとにした最小構成です。
まずは共通列だけで回し、プロジェクト固有の承認者や依存先、関連チケットの列は後から足せる形にしておくと、別の repo へ横展開するときに詰まりません。

棚卸しシート

移行前の棚卸しは、コード本体よりも「どこで確認できるか」まで書いておくと、切替日当日の迷いが減ります。
設定値だけを埋めると、確認担当が変わった瞬間に止まりやすいので、UI で見るのか CLI で見るのか、あるいは通知先や実行ログまで見るのかを列として持たせる構成が効きます。

5×5リスクマトリクス

リスク評価は、議論の場で言葉がぶれないことが欠かせません。
5×5 形式なら、発生可能性と影響度をそれぞれ 1〜5 で置けるので、スコアを 1〜25 で揃えられます。
Asanaのリスクマトリクス解説でも、この形が一般的な整理方法として扱われています。

この表はそのまま使ってもよいですし、別表でリスク台帳を作って紐づけても回ります。
たとえば「Webhook の送信先切替漏れ」「GITHUB_TOKEN 権限不足」「保護ブランチの条件過多で merge 停止」などを行単位で並べ、各スコアに応じて事前対策と切り戻し条件を書き添えると、会議が感覚論になりません。

段階的移行計画・手順書の骨子

段階的移行の計画書は、工程表というより「どの時点で進めてよいと判断するか」を書く文書です。
フェーズ名だけでは運用できないので、開始・終了、判定基準、切り戻し条件まで同じ行に置くと、担当者が変わっても意思決定の筋道を保てます。

手順書側は、作業の流れを文章で長く書くより、時系列で追える骨子にしておく方が現場で使えます。
私は「日時」「実行内容」「検証結果」の3点を最低限の単位にしています。
そこに必要なコマンドを差し込めば、そのまま当日版になります。

コマンドスニペット集

そのまま貼り付ける用途というより、手順書へ転記するための素片として使う想定です。
初期化系とミラー系は混ぜず、ブロックを分けておくと作業者の誤操作を防げます。
新規リポジトリ作成時の命名や基本操作が整理されており、リポジトリ名は最大 100 文字までです。
命名規約を先に決めておくと、後工程の URL 変更や通知文面の修正が減ります。

git init

git add .
git commit -m "first commit"

git remote add origin <NEW_REMOTE_URL>

git push -u origin main

git clone --mirror <OLD_REMOTE_URL>

git push --mirror <NEW_REMOTE_URL>

git remote -v

git branch -a

git tag