GitHub Enterprise Importer
を使ったリポジトリの移行について
GitHub CLI または API を使って、移行を実行できます。
GitHub CLI を使うと移行プロセスが簡単になるので、ほとんどのお客様に推奨されます。 カスタマイズのニーズが高い熟練したお客様は、API を使って、GitHub Enterprise Importer との独自の統合を構築できます。
API の使い方を確認するには、ページの上部にあるツール スイッチャーを使います。
前提条件
- 移行の試験的実行を行い、そのすぐ後で運用環境の移行を完了することを強くお勧めします。 試験的実行について詳しくは、「GitHub 製品間の移行に関する概要」をご覧ください。
- 移行されるデータと、Importer の既知のサポート制限事項を理解していることを確認します。 詳しくは、「GitHub 製品間の移行について」をご覧ください。
- 必須ではありませんが、運用環境の移行の間は作業を停止することをお勧めします。 Importer は差分移行をサポートしていないため、移行中に発生した変更は移行されません。 運用環境の移行の間に作業を停止しない場合は、これらの変更を手動で移行する必要があります。
- ユーザーは、移行元 Organization と移行先 Organization の両方で Organization の所有者である、または移行者ロールが付与されている必要があります。 詳しくは、「GitHub 製品間の移行のためのアクセスの管理」を参照してください。
- GitHub Enterprise Server 3.8 以降を使用する場合は、エクスポートしたアーカイブ用の Blob Storage を設定するには、[Management Console] にアクセスできる必要があります。
手順 1: GEI extension of the GitHub CLI をインストールする
これが初めての移行の場合は、GEI extension of the GitHub CLI をインストールする必要があります。 GitHub CLI について詳しくは、「GitHub CLI について」をご覧ください。
または、github/gh-gei
リポジトリの「リリース ページ」からスタンドアロン バイナリをダウンロードすることもできます。 gh
プレフィックスなしでバイナリを直接実行できます。
-
GitHub CLI をインストールします。 GitHub CLI のインストール手順については、GitHub CLI リポジトリを参照してください。
注: GitHub CLI のバージョン 2.4.0 以降が必要です。
gh --version
コマンドを使って、インストールされているバージョンを確認できます。 -
GEI extension をインストールします。
Shell gh extension install github/gh-gei
gh extension install github/gh-gei
GEI extension に関するヘルプが必要なときはいつでも、コマンドで --help
フラグを使用できます。 たとえば、gh gei --help
とすると使用可能なすべてのコマンドの一覧が表示され、gh gei migrate-repo --help
とすると migrate-repo
コマンドで使用できるすべてのオプションの一覧が表示されます。
手順 2: GEI extension of the GitHub CLI を更新する
GEI extension は毎週更新されます。 最新バージョンを確実に使うため、拡張機能を更新してください。
gh extension upgrade github/gh-gei
手順 3: 環境変数を設定する
GEI extension を使って GitHub Enterprise Cloud に移行するには、その前に、移行元と移行先の Organization にアクセスできる personal access token を作成してから、personal access token を環境変数として設定する必要があります。
-
GitHub Enterprise Cloud 上の移行先 Organization に対して認証を行う personal access token を作成して記録し、トークンがすべての要件を満たしていることを確認します。 詳しくは、「GitHub 製品間の移行のためのアクセスの管理」を参照してください。
-
移行元 Organization に対して認証を行う personal access token を作成して記録し、このトークンも同じ要件をすべて満たしていることを確認します。
-
personal access token に対する環境変数を設定します。次のコマンドの TOKEN は、上で記録した personal access token に置き換えます。 移行先の Organization には
GH_PAT
を使い、移行元の Organization にはGH_SOURCE_PAT
を使います。-
ターミナルを使っている場合は、
export
コマンドを使います。Shell export GH_PAT="TOKEN" export GH_SOURCE_PAT="TOKEN"
export GH_PAT="TOKEN" export GH_SOURCE_PAT="TOKEN"
-
PowerShell を使っている場合は、
$env
コマンドを使います。Shell $env:GH_PAT="TOKEN" $env:GH_SOURCE_PAT="TOKEN"
$env:GH_PAT="TOKEN" $env:GH_SOURCE_PAT="TOKEN"
-
手順 4: BLOB ストレージを設定する
多くの GitHub Enterprise Server インスタンスはファイアウォールの内側にあるため、GitHub がアクセスできるデータを格納するための中間的なの場所として、BLOB ストレージを使用します。
まず、サポートされているクラウド プロバイダーを使用して BLOB ストレージを設定する必要があります。 次に、[Management Console] または GitHub CLI でストレージ プロバイダーの資格情報を構成する必要があります。
サポートされているクラウド プロバイダーを使用した BLOB ストレージの設定
GitHub CLI は、次の BLOB ストレージ プロバイダーをサポートしています。
- アマゾン ウェブ サービス (AWS) S3
- Azure Blob Storage
AWS S3 ストレージ バケットの設定
AWS で、S3 バケットを設定します。 詳しくは、AWS のドキュメント「バケットの作成」をご覧ください。
次のアクセス許可を持つ AWS アクセス キーと秘密鍵も必要です。
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:ListBucketMultipartUploads",
"s3:AbortMultipartUpload",
"s3:ListBucket",
"s3:DeleteObject",
"s3:ListMultipartUploadParts"
],
"Resource": [
"arn:aws:s3:::github-migration-bucket",
"arn:aws:s3:::github-migration-bucket/*"
]
}
]
}
注: GitHub Enterprise Importer は、移行の完了後に AWS からアーカイブを削除しません。 ストレージ コストを減らすため、一定期間後にアーカイブが自動削除されるよう構成することをお勧めします。 詳しくは、AWS のドキュメントの「バケットのライフサイクル設定の指定」をご覧ください。
Azure Blob Storage ストレージ アカウントの設定
Azure でストレージ アカウントを作成し、接続文字列を記録しておきます。 詳しくは、Microsoft Docs の「ストレージ アカウント アクセス キーを管理する」をご覧ください。
注: GitHub Enterprise Importer は、移行の完了後に Azure Blob Storage からアーカイブを削除しません。 ストレージ コストを減らすため、一定期間後にアーカイブが自動削除されるよう構成することをお勧めします。 詳しくは、Microsoft Docs の「データ ライフサイクルを自動管理してコストを最適化する」をご覧ください。
BLOB ストレージ資格情報の構成
サポートされているクラウド プロバイダーを使用して BLOB ストレージを設定した後、GitHub でストレージ プロバイダーの資格情報を構成する必要があります。
- GitHub Enterprise Server 3.8 以降を使用している場合は、[Management Console] で資格情報を構成します。
- GitHub Enterprise Server 3.7 以前を使用している場合は、GitHub CLI で資格情報を構成します。
お使いの GitHub Enterprise Server インスタンス の [Management Console] での BLOB ストレージの構成
注: GitHub Enterprise Server 3.8 以降を使用している場合にのみ、[Management Console] で BLOB ストレージを構成する必要があります。 3.7 以前を使用している場合は、代わりに GitHub CLI で資格情報を構成します。
AWS S3 ストレージ バケットまたは Azure Blob Storage ストレージ アカウントを設定したら、お使いの GitHub Enterprise Server インスタンス の [Management Console] で BLOB ストレージを構成します。 [Management Console] について詳しくは、「管理コンソールからのインスタンスの管理」をご覧ください。
-
GitHub Enterprise Server の管理アカウントから、任意のページの右上隅にある をクリックします。
-
[サイト管理者] ページが表示されていない場合は、左上隅の [サイト管理者] をクリックします。1. [ サイト管理者] サイドバーで [Management Console] をクリックします。
-
[Management Console] にログインします。
-
上部のナビゲーション バーで [設定] をクリックします。
-
[移行] で、 [GitHub の移行を有効にする] をクリックします。
-
GitHub Actions に構成したストレージの設定をインポートする必要がある場合は、 [Actions からストレージの設定をコピーする] をオンにします。 詳しくは、「Azure Blob ストレージで GitHub Actions を有効化する」と「Amazon S3 ストレージで GitHub Actions を有効化する」をご覧ください。
注: ストレージ設定をコピーした後も、GitHub Enterprise Importer で動作するようにクラウド ストレージ アカウントの構成を更新する必要がある場合があります。 特に、GitHub の IP アドレスを許可リストに載せる必要があります。 詳しくは、「GitHub 製品間の移行のためのアクセスの管理」を参照してください。
-
GitHub Actions からストレージの設定をインポートしない場合は、 [Azure Blob Storage] または [Amazon S3] を選び、必要な詳細を入力します。
注: Amazon S3 を使用する場合は、バケットが配置されている AWS リージョンの標準エンドポイントに 「AWS サービス URL」 を設定する必要があります。 たとえば、バケットが
eu-west-1
リージョンにある場合、「AWS サービス URL」 はhttps://s3.eu-west-1.amazonaws.com
です。 GitHub Enterprise Server インスタンスのネットワークでは、このホストへのアクセスを許可する必要があります。 ゲートウェイ エンドポイントはサポートされていません。次にbucket.vpce-0e25b8cdd720f900e-argc85vg.s3.eu-west-1.vpce.amazonaws.com
のような例を示します。 ゲートウェイエンドポイントの詳細については、AWS ドキュメントの Amazon S3 ゲートウェイエンドポイントを参照してください。 -
[ストレージの設定をテストする] をクリックします。
-
Save settings をクリックします。
GitHub CLI での BLOB ストレージ資格情報の構成
注: GitHub Enterprise Server 3.7 以前を使用している場合にのみ、GitHub CLI で BLOB ストレージの資格情報を構成する必要があります。 3.8 以降を使用している場合は、代わりに [Management Console] で BLOB ストレージを構成します。
GitHub CLI で BLOB ストレージの資格情報を構成した場合、Git ソースまたはメタデータのエクスポートが 2 GB を超える移行を実行することはできません。 これらの移行を実行するには、GitHub Enterprise Server 3.8 以降にアップグレードしてください。
GitHub CLI での AWS S3 資格情報の構成
移行を実行する準備ができたら、リージョン、アクセス キー、シークレット キー、セッション トークンなどの AWS 資格情報を GitHub CLI に提供します (必要な場合)。 引数として渡すことも、AWS_REGION
、AWS_ACCESS_KEY_ID
、AWS_SECRET_ACCESS_KEY
、AWS_SESSION_TOKEN
という環境変数を設定することもできます。
また、--aws-bucket-name
引数を使って S3 バケットの名前で渡す必要があります。
GitHub CLI での Azure Blob Storage アカウント資格情報の構成
移行を実行する準備ができたら、接続文字列を引数として GitHub CLI に渡すか、AZURE_STORAGE_CONNECTION_STRING
という名前の環境変数を使って渡すことができます。
手順 5: 移行スクリプトを生成する
複数のリポジトリを GitHub Enterprise Cloud に一度に移行したい場合は、GitHub CLI を使って移行スクリプトを生成します。 結果のスクリプトには、リポジトリごとに 1 つの移行コマンドのリストが含まれます。
注: スクリプトを生成すると、PowerShell スクリプトが出力されます。 ターミナルを使っている場合は、.ps1
ファイル拡張子を持つスクリプトを出力し、Mac または Linux 用の PowerShell をインストールして実行する必要があります。
1 つのリポジトリを移行する場合は、次のステップに進んでください。
移行スクリプトの生成
お使いの GitHub Enterprise Server インスタンス 用の API にアクセスできるコンピューターから、このステップを行う必要があります。 ブラウザーからインスタンスにアクセスできる場合、そのコンピューターには正しいアクセス権があります。
移行スクリプトを生成するには、gh gei generate-script
コマンドを実行します。
GitHub Enterprise Server 3.8 以降の場合、または Azure Blob Storage で 3.7 以前を使っている場合は、次のフラグを使ってください。
gh gei generate-script --github-source-org SOURCE \ --github-target-org DESTINATION \ --output FILENAME \ --ghes-api-url GHES-API-URL
gh gei generate-script --github-source-org SOURCE \
--github-target-org DESTINATION \
--output FILENAME \
--ghes-api-url GHES-API-URL
AWS S3 で GitHub Enterprise Server 3.7 以前を使っている場合は、次のフラグを使ってください。
gh gei generate-script --github-source-org SOURCE \ --github-target-org DESTINATION \ --output FILENAME \ --ghes-api-url GHES-API-URL \ --aws-bucket-name AWS-BUCKET-NAME
gh gei generate-script --github-source-org SOURCE \
--github-target-org DESTINATION \
--output FILENAME \
--ghes-api-url GHES-API-URL \
--aws-bucket-name AWS-BUCKET-NAME
お使いの GitHub Enterprise Server インスタンス で自己署名証明書または無効な SSL 証明書が使われている場合は、--no-ssl-verify
フラグを使います。 このフラグを使うと、GitHub CLI は、ユーザーのインスタンスのみからデータを抽出するときは、SSL 証明書の検証をスキップします。 その他のすべての呼び出しでは、SSL が検証されます。
移行された各リポジトリの移行ログをダウンロードするスクリプトが必要な場合は、--download-migration-logs
フラグを追加します。 移行ログについて詳しくは、「GitHub Enterprise Importer の移行ログへのアクセス」をご覧ください。
上のコマンドのプレースホルダーを次の値に置き換えます。
プレースホルダー | 値 |
---|---|
SOURCE | 移行元の Organization の名前 |
DESTINATION | 移行先の Organization の名前 |
FILENAME | 結果の移行スクリプトのファイル名 ターミナルを使っている場合は、生成されたスクリプトの実行に PowerShell が必要なので、 .ps1 ファイル拡張子を使います。 Mac 用または Linux 用の PowerShell をインストールできます。 |
GHES-API-URL | お使いの GitHub Enterprise Server インスタンス の API の URL (例: https:/ ) |
AWS-BUCKET-NAME | AWS S3 バケットのバケット名 |
移行スクリプトの確認
スクリプトを生成したら、ファイルを確認し、必要に応じてスクリプトを編集します。
- 移行したくないリポジトリがある場合は、対応する行を削除するかコメントにします。
- 移行先の Organization でリポジトリに別の名前を使う場合は、対応する
--target-repo
フラグの値を更新します。
注: リポジトリに 10 GB を超えるリリース データがある場合、リリースを移行することはできません。 リリースなしでリポジトリを移行するには、--skip-releases
フラグを使います。
GEI の拡張機能としてではなく、スタンドアロン バイナリとして GitHub CLI をダウンロードした場合は、生成されたスクリプトを更新して gh gei
ではなくバイナリを実行する必要があります。
手順 6: リポジトリを移行する
移行スクリプトを使って複数のリポジトリを移行すること、または gh gei migrate-repo
コマンドを使って 1 つのリポジトリを移行することができます。
リポジトリを移行するとき、GEI extension of the GitHub CLI で次の手順が実行されます。
- お使いの GitHub Enterprise Server インスタンス に接続し、リポジトリごとに 2 つの移行アーカイブを生成します。1 つは Git ソース、もう 1 つはメタデータのファイルです
- 移行アーカイブを任意の BLOB ストレージ プロバイダーにアップロードします
- BLOB ストレージ プロバイダーに格納されているアーカイブの URL を使用して、GitHub Enterprise Cloud で移行を開始します
- ローカル コンピューターから移行アーカイブを削除します
複数のリポジトリを移行する
スクリプトを実行するために GitHub Enterprise Server 3.7 以前から移行する場合、環境変数を追加で設定して BLOB ストレージ プロバイダーに対して認証を行う必要があります。
-
Azure Blob Storage の場合は、
AZURE_STORAGE_CONNECTION_STRING
を Azure ストレージ アカウントの接続文字列に設定します。ストレージ アカウントのアクセス キーを使う接続文字列のみがサポートされています。 Shared Access Signature (SAS) を使う接続文字列はサポートされていません。 ストレージ アカウントのアクセス キーについて詳しくは、Azure のドキュメントの「ストレージ アカウント アクセス キーを管理する」をご覧ください。
-
AWS S3 の場合は、次の環境変数を設定します。
AWS_ACCESS_KEY
: バケットのアクセス キーAWS_SECRET_KEY
: バケットの秘密鍵AWS_REGION
: バケットが配置されている AWS リージョンAWS_SESSION_TOKEN
: AWS の一時的な資格情報を使っている場合のセッション トークン (AWS ドキュメントの「AWS リソースで一時的な資格情報を使用する」をご覧ください)
複数のリポジトリを移行するには、上で生成したスクリプトを実行します。 次のコマンドの FILENAME を、スクリプトの生成時に指定したファイル名に置き換えます。
-
ターミナルを使っている場合は、
./
を使います。Shell ./FILENAME
./FILENAME
-
PowerShell を使っている場合は、
.\
を使います。Shell .\FILENAME
.\FILENAME
1 つのリポジトリを移行する
お使いの GitHub Enterprise Server インスタンス 用の API にアクセスできるコンピューターから、このステップを行う必要があります。 ブラウザーからインスタンスにアクセスできる場合、そのコンピューターには正しいアクセス権があります。
1 つのリポジトリを移行するには、gh gei migrate-repo
コマンドを使います。
GitHub Enterprise Server 3.8 以降を使っている場合は、次のフラグを使ってください。
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME --ghes-api-url GHES-API-URL
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME --ghes-api-url GHES-API-URL
GitHub Enterprise Server 3.7 以前から移行していて、BLOB ストレージ プロバイダーとして Azure Blob Storage を使っている場合は、次のフラグを使って認証してください。
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \ --ghes-api-url GHES-API-URL --azure-storage-connection-string "AZURE_STORAGE_CONNECTION_STRING"
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
--ghes-api-url GHES-API-URL --azure-storage-connection-string "AZURE_STORAGE_CONNECTION_STRING"
GitHub Enterprise Server 3.7 以前から移行していて、BLOB ストレージ プロバイダーとして Amazon S3 を使っている場合は、次のフラグを使って認証してください。
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \ --ghes-api-url GHES-API-URL --aws-bucket-name "AWS-BUCKET-NAME"
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
--ghes-api-url GHES-API-URL --aws-bucket-name "AWS-BUCKET-NAME"
お使いの GitHub Enterprise Server インスタンス で自己署名証明書または無効な SSL 証明書が使われている場合は、--no-ssl-verify
フラグを使います。 このフラグを使うと、GitHub CLI は、ユーザーのインスタンスのみからデータを抽出するときは、SSL 証明書の検証をスキップします。 その他のすべての呼び出しでは、SSL が検証されます。
注: リポジトリに 10 GB を超えるリリース データがある場合、リリースを移行することはできません。 リリースなしでリポジトリを移行するには、--skip-releases
フラグを使います。
上のコマンドのプレースホルダーを次の値に置き換えます。
プレースホルダー | 値 |
---|---|
SOURCE | 移行元の Organization の名前 |
CURRENT-NAME | 移行するリポジトリの名前 |
DESTINATION | 移行先の Organization の名前 |
NEW-NAME | 移行されたリポジトリに設定する名前 |
GHES-API-URL | お使いの GitHub Enterprise Server インスタンス の API の URL (例: https:/ ) |
AZURE_STORAGE_CONNECTION_STRING | Azure ストレージ アカウントの接続文字列。 接続文字列は必ず引用符で囲みます。それには、シェルで誤って解釈される可能性がある文字が含まれます。 |
AWS-BUCKET-NAME | AWS S3 バケットのバケット名 |
移行を取り消す場合は、MIGRATION-ID を abort-migration
返された( migrate-repo
から)ID に置き換えて、コマンドを使用します。
gh gei abort-migration --migration-id MIGRATION-ID
gh gei abort-migration --migration-id MIGRATION-ID
手順 7: 移行を検証し、エラー ログを確認する
移行が完了したら、移行ログを確認することをお勧めします。 詳しくは、「GitHub Enterprise Importer の移行ログへのアクセス」を参照してください。
移行したリポジトリで健全性チェックを確認することをお勧めします。
移行が完了したら、ストレージ コンテナーからアーカイブを削除することをお勧めします。 追加の移行を実行する予定の場合は、ADO2GH extension によってストレージ コンテナーに配置されたアーカイブを削除します。 移行が完了したら、コンテナー全体を削除できます。