GitHub Enterprise Server から GHE.com へのライブ マイグレーションのトラブルシューティング

移行で発生する可能性がある問題に関するアドバイス。

この記事で

メモ

Enterprise Live Migrations は パブリック プレビュー であり、変更される可能性があります。

移行で問題が発生した場合は、 elm migration status --migration-id MIGRATION-ID で移行の状態を確認し、エラー情報を確認します。

地位Meaning推奨されるアクション
Created移行は作成されましたが、まだ開始されていません
elm migration start を実行します。
キュー登録移行が開始されるのを待っていますWait
エクスポートソースからデータがエクスポートされている
elm migration statusを用いて監視する
プロセスエクスポートされたデータがインポート先に取り込まれている
elm migration statusを用いて監視する
カットオーバーの準備完了最初の移行が完了し、カットオーバーに向けて移行準備が整いました。準備ができたら、次を実行します。 elm migration cutover-to-destination
カットオーバーソース リポジトリがロックされ、残りの変更が宛先に適用されているモニター;状態が [完了] に切り替わります
Completed移行が正常に完了しました宛先リポジトリを確認し、マネキンを回収する
失敗移行で回復不能なエラーが発生しましたエラーを調査する (下記参照)
一時停止移行が一時停止されている一時停止の理由を確認し、解決します (下記参照)
終了移行が取り消されましたN/A
劣化宛先に到達できないGitHub Enterprise Server アプライアンスと GHE.com の間のネットワーク接続を確認する (下記参照)

移行の状態が "失敗" である

回復不可能なエラーによって続行できない場合、移行は 失敗 状態になります。 これは、インポートに失敗した個々のリソースとは異なります。失敗した移行は、移行自体を続行できないことを意味します。

調査するには、 elm migration status --migration-id MIGRATION-ID を実行し、応答のエラーの詳細を確認します。 各エラーには、 (Correlation ID for Support: UUID)形式の関連付け ID が含まれます。 GitHub のサポートにお問い合わせの場合は、サポート チームが調査できるように、この ID を指定します。

基になる問題を解決したら、失敗した移行を elm migration cancel --migration-id MIGRATION-ID で中止し、新しい移行を開始します。

移行の状態が "一時停止" である

問題が続行する前に介入が必要な場合、移行は 一時停止 状態になります。 elm migration status --migration-id MIGRATION-ID実行し、一時停止の理由を確認します。

一般的な一時停止の理由:

  • 資格情報の有効期限: personal access tokens (classic) の 1 つが期限切れになりました。 必要なスコープで新しいトークンを作成し、 elm credential updateで更新します。 次に、移行を再開します。
  • レート制限: 移行が API のレート制限に達しました。 数分待ってから再起動します。

基になる問題を解決した後、一時停止した移行を再開するには:

elm migration start --migration-id MIGRATION-ID

移行の状態が「劣化」である

機能低下状態は、GitHub Enterprise Server アプライアンス上の移行サービスが移行先企業に到達できないことを意味します。 移行はソース側で続行されますが、移行先の状態は不明です。

GitHub Enterprise Server アプライアンスと GHE.com のサブドメイン間のネットワーク接続を確認してから、elm migration status --migration-id MIGRATION-IDをもう一度実行します。 状態の応答には、接続先との最後に成功した連絡先のタイムスタンプが含まれています。これは、接続の問題が発生している期間を評価するのに役立ちます。

"エクスポート" で移行が停止する

移行が エクスポート状態のまま で、進行状況が 30 分以上変化しない場合、エクスポーターが停止する可能性があります。

  1. elm migration status --migration-id MIGRATION-ID実行し、リソース数が変更されているかどうかを確認します。

  2. カウントが静的な場合は、アプライアンスの宛先へのネットワーク接続を確認します。

  3. GitHub Enterprise Server アプライアンスでエクスポーター ログを確認します (SSH 管理者アクセスが必要)。

    Shell
    journalctl -t elm-exporter-backfiller --since "1 hour ago" | tail -50
journalctl -t elm-exporter-sender --since "1 hour ago" | tail -50

  4. エクスポーター タスクがクラッシュした場合は、自動的に回復します。 そうでない場合は、 GitHub のサポートにお問い合わせください。

Git 同期が完了しない

elm migration status、長期間経過しても初期 Git プッシュが完了しなかったことが示されている場合は、Git 同期ログを確認します。

Shell
journalctl -t elm-exporter-git-syncer --since "2 hours ago"

以下を探してください:

  • connection refused: GitHub Enterprise Server アプライアンスと宛先の間のネットワークの問題。 ファイアウォール規則と DNS 解決を確認します。
  • authentication failed: personal access token (classic) に必要なスコープが不足しているか、有効期限が切れている可能性があります。
  • remote: error: 宛先がプッシュを拒否している可能性があります。 エラーの詳細を GitHub のサポート にお問い合わせください。

一部のリソースのインポートに失敗しました

個々のリソースは、移行全体が失敗することなくインポートに失敗する可能性があります。 elm migration status --migration-id MIGRATION-IDの出力で、失敗したリソースの数を確認できます。

失敗したリソースは、すべての自動再試行が使い果たされた後にのみ表示されるため、表示されるエラーは、介入なしで解決不可能として確認されます。 状態の応答でエラーの詳細を確認します。バックフィルまたはライブ更新で失敗した各リソースが "state": "failed"表示されます。

失敗したリソースの数と種類が許容される場合は、カットオーバーを続行できます。 そうでない場合は、移行を中止し、基になる問題を解決してから、新しい移行を開始します。

カットオーバーに失敗し、ソース リポジトリがロックされている

途中でカットオーバーが失敗した場合、ソース リポジトリはロックまたはアーカイブされたままになる可能性があります。 これにより、移行先がまだ不完全な場合でも、開発者がソースにプッシュできなくなります。

ソース リポジトリのロックを解除するには、サイト管理者が GitHub Enterprise Server[Management Console]からロックを解除する必要があります。

ソースのロックが解除されたら、 elm migration cutover-to-destination --migration-id MIGRATION-IDを使用してカットオーバーを再試行するか、 elm migration cancel --migration-id MIGRATION-ID を使用して移行を中止し、準備ができたら新しい移行を開始できます。

強制プッシュにより、移行を再開する必要があります。

移行の進行中に誰かがソース リポジトリの既定のブランチに強制的にプッシュすると、ソースと宛先の間の Git 同期が中断されます。 コミット履歴を書き換える強制プッシュは、段階的に調整することができません。

その場合は、 elm migration cancel --migration-id MIGRATION-ID を使用して移行を中止し、新しい移行を開始します。 再起動する前に、移行中は既定のブランチへの強制プッシュが許可されていないことをチームに伝えてください。

アクセス トークンが拒否されました

認証エラーで移行が失敗した場合は、次のことを確認します。

  • ソース トークンと宛先トークンの両方が personal access tokens (classic)。 きめ細かいトークンはサポートされていません。
  • トークンには、 Enterprise Live Migrations を使用したリポジトリの移行 で指定されたスコープがあります。
  • 宛先組織が SAML シングル サインオンを適用する場合、トークンは SSO に対して承認されている必要があります。

最近トークンをローテーションした場合、移行によって新しい資格情報が自動的に取得されます。 ghe-config-applyを実行したり、移行サービスを再起動したりする必要はありません。

ソース GHES URL が拒否されました

Enterprise Live Migrations には、HTTPS を使用するための GitHub Enterprise Server URL が必要です。 URL が HTTP で構成されている場合、移行はプレフライト検証に失敗します。

サポートのためのログの収集

GitHub のサポートに連絡する場合、最も便利な成果物は次のとおりです。

  1. サポート バンドル (推奨): ghe-support-bundle -u アプライアンスでGitHub Enterprise Serverを実行します。 これにより、すべての ELM ログが自動的にキャプチャされます。
  2. 移行状態の出力: elm migration status --migration-id MIGRATION-ID
  3. 移行 ID とおおよその失敗時間 (タイムゾーンあり)
  4. エラー メッセージ内の相関 IDすべて

サポート バンドルが不可能な場合は、ログを手動で収集できます。

Shell
journalctl -t elm-exporter-migration-manager --since "24 hours ago" > migration-manager.log
journalctl -t elm-exporter-backfiller --since "24 hours ago" > backfiller.log
journalctl -t elm-exporter-sender --since "24 hours ago" > sender.log
journalctl -t elm-exporter-git-syncer --since "24 hours ago" > git-syncer.log