GitHub Enterprise Importer を使用した移行のトラブルシューティング

GitHub Enterprise Importer

のトラブルシューティング手順について

移行が失敗した場合、または予期しない結果が発生した場合は、以下に示すトラブルシューティングの最初の手順を試してください。これにより、一般的にさまざまな問題が解決します。これらの最初の手順で問題が解決しない場合は、移行のログにエラーメッセージがないか確認します。次に、この記事のエラーメッセージを見つけて、解決の手順を試してください。

エラーメッセージのトラブルシューティング手順を試したにもかかわらず問題を解決できない場合は、GitHub Support にお問い合わせください。

トラブルシューティングの最初の手順

さらに調査する前に、一般的にさまざまな問題を解決するこれらのトラブルシューティング手順を試してください。

移行に使用している GitHub CLI 拡張機能の最新バージョンを使用していることを確認します。そうでない場合は、最新バージョンにアップグレードします。
すべてのアクセス要件を満たしていることを確認します。詳細については、移行パスに適した記事を参照してください。
移行をもう一度実行してみます。一部の移行の問題は一時的なもので、2 回目を試してみるとうまくいくことがあります。
同様のデータがある別のリポジトリで移行を実行してみます。これは、issue がリポジトリに固有であるか、より広範なデータシェイプの問題を表しているかを判断するのに役立ちます。

これらの手順で問題が解決しない場合は、移行ログのエラーメッセージを確認します。確認する必要があるログは、移行が失敗したか成功したかによって異なります。

失敗した移行のトラブルシューティング

移行に失敗した場合は、移行ごとに GitHub CLI によって生成された詳細ログエントリを確認します。このログファイルは、移行を実行したのと同じディレクトリに保存されます。

このログには、発行した各コマンドと、それに応じて GitHub CLI で行われたすべての API 要求のレコードが含まれています。失敗とエラーメッセージは、通常、ログの終わりの方に表示されます。

移行を実行できない
リソースが Organization の SAML 強制によって保護されている
401 Unauthorized 応答
404 Not Found 応答
Archive generation failed 応答
cipher name is not supported エラー
Subsystem 'sftp' could not be executed エラー
Source export archive... does not exist エラー
Repository rule violations found エラー
Your push would publish a private email address エラー

No access to createMigrationMutation や Missing permissions のようなエラーが表示された場合、ご自身の個人アカウントに移行を実行するために必要なアクセス権がありません。自分が Organization の所有者であるか、移行者ロールを付与されていることを確認します。移行者ロールの付与について詳しくは、「GitHub Enterprise Importer について」を参照してください。

メモ: GitHub 製品間で移行する場合は、自分が Organization の所有者であること、または移行元と移行先の両方の Organization の移行者ロールが自分に付与されていることを確認します。

リソースが Organization の SAML 強制によって保護されている

このエラーは、GitHub CLI に入力した personal access token が SAML シングルサインオンでの使用を承認されている必要があることを示します。詳しくは、「SAMLシングルサインオンで利用するために個人アクセストークンを認可する」を参照してください。

`401 Unauthorized` 応答

401 状態コードを含むエラーは、通常、GitHub CLI に入力した personal access token に必要なスコープが設定されていないことを示します。入力した personal access token のスコープを検証します。必要なスコープの詳細については、移行パスに適した記事を参照してください。

`404 Not Found` 応答

404 状態コードを含むエラーは、通常、いずれかのコマンドでの入力ミスを示します。入力した正確なコマンドの移行ログを確認し、移行元のリポジトリ、Organization、またはプロジェクトに入力ミスがないか確認します。

`Archive generation failed` 応答

GitHub Enterprise Server から移行するときに Archive generation failed... 応答を受け取った場合、リポジトリが大きすぎる可能性があります。リポジトリのサイズ制限について詳しくは、「GitHub 製品間の移行について」を参照してください。

まず、migrate-repo コマンドで --skip-releases フラグを使用して、移行からリリースを除外してみてください。

それでもうまくいかない場合は、GitHub Enterprise Server 3.8.0 以降にアップグレードすることをお勧めします。アップグレードできない場合は、別のオプションとして、ghe-migrator を使用してリポジトリアーカイブを手動で生成することもできます。

リポジトリの移行アーカイブを生成します。一度にエクスポートするリポジトリは 1 つだけにする必要があります。手順については、「Enterprise から移行データをエクスポートする」を参照してください。
任意の BLOB ストレージプロバイダーに移行アーカイブをアップロードします。
AWS S3 の署名済み URL や Azure Blob Storage の SAS URL など、GitHub からアクセスできる有効期間の短い移行アーカイブの URL を生成します。
--git-archive-url と --metadata-archive-url の両方のフラグを前の手順のアーカイブの URL に設定して migrate-repo コマンドを呼び出します。

`cipher name is not supported` エラー

Bitbucket Server から移行していて、移行の実行時に cipher name aes256-ctr for openssh key file is not supported のようなエラーが表示された場合は、サポートされていない暗号が SSH 秘密キーで使用されています。サポートされている暗号について詳しくは、「Bitbucket サーバーからの移行のアクセスの管理」を参照してください。

互換性のある新しい SSH キーペアを生成するには、次のコマンドを実行します。

Shell

ssh-keygen -t ed25519 -Z aes256-cbc -C "your_email@example.com"

ssh-keygen -t ed25519 -Z aes256-cbc -C "your_email@example.com"

新しい SSH キーペアを生成した後、キーを使用する前に、公開キーを Bitbucket Server インスタンスの authorized_keys に追加する必要があります。

`Subsystem 'sftp' could not be executed` エラー

Bitbucket Server から移行していて Subsystem 'sftp' could not be executed のようなエラーが発生する場合は、サーバー上で SFTP が有効になっていないか、ユーザーアカウントに SFTP アクセス権がありません。

サーバー管理者に連絡して、ユーザーアカウントでの SFTP アクセス権の有効化を依頼する必要があります。

`Source export archive... does not exist` エラー

Bitbucket Server から移行していて、Source export archive (/var/atlassian/application-data/bitbucket/shared/migration/export/Bitbucket_export_1.tar) does not exist のようなエラーが発生する場合は、GitHub CLI が、Bitbucket Server インスタンスの間違った場所で移行アーカイブを探しています。

この問題を解決するには、gh bbs2gh migrate-repo の --bbs-shared-home 引数を、Bitbucket Server または Data Center の共有ホームディレクトリに設定します。既定の共有ホームディレクトリは /var/atlassian/application-data/bitbucket/shared ですが、構成が異なる場合があります。

Bitbucket Server で共有ホームディレクトリを確認できます。

Bitbucket Server または Data Center のインスタンスの管理領域に移動します。
サイドバーの [システム] で、[ストレージ] をクリックします。
[共有ディレクトリ] で、サーバーの共有ホームディレクトリの場所を確認します。

複数のメモを含むクラスターモードで Bitbucket Data Center を実行している場合、共有ディレクトリはクラスターノード間で共有されており、各ノードの同じ場所にマウントする必要があります。

`Repository rule violations found` エラー

GH013: Repository rule violations found for refs/heads/main などの Repository rule violations found エラーが発生する場合は、移行元のリポジトリ内のデータが、移行先の組織で構成されているルールセットと競合しています。詳しくは、「ルールセットについて」を参照してください。

移行の間に一時的にルールセットを無効にするか、バイパスモードまたはバイパスリストを使って、構成されているルールから移行を除外することができます。詳しくは、「組織内のリポジトリのルールセットを管理する」を参照してください。

`Your push would publish a private email address` エラー

GH007: Your push would publish a private email address (プッシュにより、プライベートメールアドレスが公開されます) とともに Git source migration failed (Git ソースの移行に失敗しました) エラーが発生した場合、移行しようとしている Git ソースに、GitHub へのプッシュをブロックしたメールアドレスによって作成されたコミットが含まれます。詳しくは、「個人のメールアドレスを公開するコマンドラインのプッシュのブロック (GitHub Enterprise Cloud のドキュメント) を参照してください。

このエラーを解決するには、Git 履歴を書き換えてメールアドレスを削除するか、[電子メールを公開するコマンドラインプッシュをブロックする] 設定を無効にします。

移行ログの警告について

移行が成功した場合でも、移行ログを確認して警告をチェックする必要があります。

移行ログの警告は、移行できなかったリポジトリ内の特定の項目を指します。詳しくは、「GitHub Enterprise Importer の移行ログへのアクセス」を参照してください。

注: "移行ログ" issue の最後に "移行完了" が含まれている場合、リポジトリは移行されました。警告は、リポジトリ内の特定の項目 (pull request のコメントなど) が正しく移行されていない可能性があることのみを示します。

警告：「リポジトリメタデータが大きすぎて移行できない」
警告：「コメントが差分にない」
警告：「Pull Request Review...エラーが発生したため、インポートできませんでしたREVIEW_THREAD_MISSING_END_COMMIT_OID」
Organization の移行後にチーム参照が壊れる

警告：「リポジトリメタデータが大きすぎて移行できない」

"移行ログ" の issue または GitHub CLI に "リポジトリメタデータが大きすぎて移行できない" と表示された場合、リポジトリが最大アーカイブサイズである 10 GB を超えています。これは、多くの場合、大規模なリリース資産が原因で発生します。 migrate-repo コマンドで --skip-releases フラグを使用して、移行からリリースを除外してみてください。

警告：「コメントが差分にない」

Azure DevOps から移行する場合、pull request で変更されなかった行の pull request コメントを GitHub に移行することはできません。この理由で移行できないすべてのコメントに対して、この警告が表示されます。

メモ: pull request で変更されなかった行のコメントのみが、この制限の影響を受けます。 pull request で変更された行のコメントは移行されます。

影響を受けるコメントは移行されたリポジトリには含まれませんが、これらの警告に対してユーザーによるそれ以上のアクションは必要ありません。

警告：「Pull Request Review...エラーが発生したため、インポートできませんでしたREVIEW_THREAD_MISSING_END_COMMIT_OID」

この警告は、レビューがアタッチされているコミットが存在しなくなったため、pull requestレビューを移行できなかった場合に発生します。

これは通常、コミットがフォースプッシュで削除されたか、ブランチが削除された場合に発生します。

この場合、コメントは失われませんが、特定のコミットにアタッチされたレビューとしてではなく、履歴を保持するためのインライン pull requestコメントとして移行されます。

Organization の移行後にチーム参照が壊れる

チームへの参照 (@octo-org/octo-team など) は、Organization の移行の一部として更新されません。これにより、CODEOWNERS ファイルが期待どおりに動作しないなど、移行先の Organization で問題が発生する可能性があります。

移行後にこれらの参照を更新することも、移行元の Organization の名前を変更してチーム名を保持し、移行先 Organization の元の名前を使用することもできます。

たとえば、移行元 Organization が @octo-org で、CODEOWNERS ファイルにチーム @octo-org/octo-team への参照が含まれている場合は、移行前に移行元 Organization の名前を @octo-org-temp に変更し、新しい Organization の名前として @octo-org を使用できます。そうすると、移行されたチームは @octo-org/octo-team と呼ばれ、移行されたリポジトリ内の CODEOWNERS ファイルは予期したとおりに動作します。

ロックされたリポジトリ

移行後、ソースまたは移行先のリポジトリがロックされ、リポジトリのコードとそのすべてのリソース (issue や pull request など) へのアクセスが無効になる場合があります。ロックされたリポジトリについて詳しくは、「ロックされたリポジトリについて」を参照してください。

リポジトリのロックを解除するプロセスは、リポジトリが格納されている GitHub 製品によって異なります。

ロックされたリポジトリが GitHub Enterprise Server にある場合、サイト管理者は、サイト管理者ダッシュボードを使用してリポジトリのロックを解除できます。詳しくは、GitHub Enterprise Server ドキュメントの「リポジトリのロック."
ロックされたリポジトリが GitHub.com にある場合、サイト管理者に連絡してリポジトリのロックを解除できます。

注: 移行が失敗した場合、必ずしもすべてのデータが移行されたとは限りません。リポジトリのロックを解除して使用すると、データが失われます。ロックされたリポジトリを削除して、移行を再試行することをお勧めします。

GitHub Support への連絡

上記のトラブルシューティング手順を試しても問題を解決できない場合は、GitHub Support ポータルから GitHub Support に問い合わせてください。

GitHub Enterprise Importer を使用した移行のトラブルシューティング

この記事の内容