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

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

この記事で

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

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

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

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

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

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

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

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

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

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

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

gh elm migration start --migration-id MIGRATION-ID

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

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

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

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

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

  1. gh 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 同期が完了しない

gh 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 のサポート にお問い合わせください。

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

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

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

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

カットオーバーに失敗し、ソース リポジトリが使用できない

ソース リポジトリのアーカイブ後にカットオーバーが失敗した場合、 ELM サービスはリポジトリのアーカイブ解除を試みます。 これが失敗した場合、リポジトリ管理者はリポジトリのアーカイブを解除できます。 「リポジトリのアーカイブ」を参照してください。

リポジトリのアーカイブを解除すると、リポジトリ内のすべての問題と pull request が Elasticsearch でインデックスが再作成されるため、インスタンスに追加の負荷が発生することに注意してください。

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

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

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

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

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

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

  • ソース トークンと宛先トークンの両方が personal access tokens (classic)。 Fine-grained personal access tokens はサポートされていません。
  • 宛先組織が SAML シングル サインオンを適用する場合、トークンは SSO に対して承認されている必要があります。
  • どちらのトークンにも 、AUTOTITLE で指定されたスコープがあります。

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

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

Enterprise Live Migrations では、2 つの資格情報セットが使用されます。 このセクションは、手順 2 で作成し、gh elm configureによってローカルに格納されたオペレーター トークンに適用されます。

オペレーターは、エンドポイントごとに personal access token (classic) を使用する必要があります。

  • ソース演算子トークンは、GitHub Enterprise Serverに作成する必要があります。
  • ターゲット演算子トークンは、GHE.comに作成する必要があります。
  • どちらのトークンにも 、AUTOTITLE で指定されたスコープがあります。
  • トークン所有者は、対応する企業の管理者である必要があります。 スコープを選択しても、ユーザーに管理アクセス権は付与されません。
  • Fine-grained personal access tokens はサポートされていません。

一般的な応答

応答Meaning対処法
401 Bad credentialsエンドポイントがトークンを認証できませんでした。 承認スコープはまだ評価されていません。トークンの有効期限が切れていないか取り消されていないこと、トークンが完全にコピーされていること、およびソース トークンとターゲット トークンが交換されていないことを確認します。 各トークンが使用されているホスト上に作成されたことを確認します。
403 Forbiddenトークンは認証されましたが、そのユーザーまたはスコープは操作を承認しません。
admin:enterpriseでpersonal access token (classic)を使用します。 トークン所有者が企業の管理者であることを確認します。 SAML SSO が適用される場合は、SSO のトークンを承認します。
Resource not accessible by personal access tokenトークンの種類またはアクセス許可はサポートされていません。 これは通常、 fine-grained personal access tokenで発生します。
admin:enterpriseを持つpersonal access token (classic)に置き換えます。
404 Not Found要求で間違った API URL が使用されている場合や、移行先企業 Enterprise Live Migrations が有効になっていない可能性があります。
GHE.comの場合は、末尾にスラッシュを付けずに、https://api.SUBDOMAIN.ghe.comなどのテナント API URL を使用します。 ソース API URL も確認します。 両方の URL が正しい場合は、 GitHub のサポート に連絡して、 Enterprise Live Migrations が有効になっていることを確認してください。

トークンを個別に検証する

Enterprise Live Migrationsで使用する前に、/user エンドポイントに対して各トークンをテストします。 これらのコマンドは応答ヘッダーを出力しますが、応答本文は破棄します。

ソース (GitHub Enterprise Server) トークンの場合:

curl --silent --show-error --output /dev/null --dump-header - \
  --header "Authorization: Bearer $SOURCE_OPERATOR_TOKEN" \
  "$SOURCE_API_URL/user"

ターゲット トークンの場合:

curl --silent --show-error --output /dev/null --dump-header - \
  --header "Authorization: Bearer $TARGET_OPERATOR_TOKEN" \
  "$TARGET_API_URL/user"

各要求は 200 OKを返す必要があります。 X-OAuth-Scopes応答ヘッダーには、admin:enterpriseを含める必要があります。

/userが200 OKを返しても、Enterprise Live Migrations コマンドが401 Bad credentialsを返す場合、CLI には別のトークンまたは URL が格納されている可能性があります。 gh elm configure再度実行し、各トークンを対応するエンドポイントに慎重に関連付けます。

オペレーター トークンは、 Enterprise Live Migrations CLI によってローカルに格納されます。 オペレーター トークンをローテーションした後、 gh elm configure をもう一度実行するか、適切なコマンド ライン オプションを使用して代替資格情報を指定します。

これは、手順 4 で構成した移行サービス トークンとは異なります。 更新された移行サービスの資格情報は自動的に取得され、 ghe-config-apply や移行サービスの再起動は必要ありません。

ログ、スクリーンショット、サポート バンドル、またはサポート要求にアクセス トークンを含めないでください。 問題が解決しない場合は、HTTP 状態、エンドポイントのホスト名、移行 ID、タイム ゾーンを含むタイムスタンプ、および関連付け ID を GitHub のサポート に指定しますが、トークンは指定しないでください。

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

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

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

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

  1. サポート バンドル (推奨): ghe-support-bundle -u アプライアンスでGitHub Enterprise Serverを実行します。 これにより、すべての Enterprise Live Migrations ログが自動的にキャプチャされます。
  2. 移行状態の出力: gh 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