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 リポジトリを参照してください。
Note
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 (classic) を作成して記録し、トークンがすべての要件を満たしていることを確認します。 詳しくは、「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"
-
-
データ所在地付き GitHub Enterprise Cloud に移行する場合は、便宜上、エンタープライズのベース API URL の環境変数を設定します。 次に例を示します。
Shell export TARGET_API_URL="https://api.octocorp.ghe.com"
export TARGET_API_URL="https://api.octocorp.ghe.com"
この変数は、GitHub CLI で実行するコマンドの
--target-api-url
オプションと共に使用します。
手順 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/*"
]
}
]
}
Note
GitHub Enterprise Importer は、移行の完了後に AWS からアーカイブを削除しません。 ストレージ コストを減らすため、一定期間後にアーカイブが自動削除されるよう構成することをお勧めします。 詳しくは、AWS のドキュメントの「バケットのライフサイクル設定の指定」をご覧ください。
Azure Blob Storage ストレージ アカウントの設定
Azure でストレージ アカウントを作成し、接続文字列を記録しておきます。 詳しくは、Microsoft Docs の「ストレージ アカウント アクセス キーを管理する」をご覧ください。
Note
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 ストレージの構成
Note
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 を有効化する」を参照してください。
Note
ストレージ設定をコピーした後も、GitHub Enterprise Importer で動作するようにクラウド ストレージ アカウントの構成を更新する必要がある場合があります。 特に、GitHub の IP アドレスを許可リストに載せる必要があります。 詳しくは、「GitHub 製品間の移行のためのアクセスの管理」をご覧ください。
-
GitHub Actions からストレージの設定をインポートしない場合は、 [Azure Blob Storage] または [Amazon S3] を選び、必要な詳細を入力します。
Note
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 ストレージ資格情報の構成
Note
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
という名前の環境変数を使って渡すことができます。
ネットワーク アクセスの許可
ストレージ アカウントでファイアウォール規則を構成している場合は、移行先の IP 範囲へのアクセスを許可していることを確認します。 「GitHub 製品間の移行のためのアクセスの管理」を参照してください。
手順 5: 移行スクリプトを生成する
複数のリポジトリを GitHub Enterprise Cloud に一度に移行したい場合は、GitHub CLI を使って移行スクリプトを生成します。 結果のスクリプトには、リポジトリごとに 1 つの移行コマンドのリストが含まれます。
Note
スクリプトを生成すると、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
プレースホルダー
上のコマンドのプレースホルダーを次の値に置き換えます。
プレースホルダー | 値 |
---|---|
SOURCE | 移行元の Organization の名前 |
DESTINATION | 移行先の Organization の名前 |
FILENAME | 結果の移行スクリプトのファイル名 ターミナルを使っている場合は、生成されたスクリプトの実行に PowerShell が必要なので、 .ps1 ファイル拡張子を使います。 Mac 用または Linux 用の PowerShell をインストールできます。 |
GHES-API-URL | お使いの GitHub Enterprise Server インスタンス の API の URL (例: https:/ ) |
AWS-BUCKET-NAME | AWS S3 バケットのバケット名 |
追加の引数
引数 | 説明 |
---|---|
--target-api-url TARGET-API-URL | GHE.com に移行する場合は、--target-api-url TARGET-API-URL を追加します。TARGET-API-URL は Enterprise のサブドメインのベース API URL です。 (例: https:/ )。 |
--no-ssl-verify | お使いの GitHub Enterprise Server インスタンス で自己署名証明書または無効な SSL 証明書が使われている場合は、--no-ssl-verify フラグを使います。 このフラグを使うと、GitHub CLI は、ユーザーのインスタンスのみからデータを抽出するときは、SSL 証明書の検証をスキップします。 その他のすべての呼び出しでは、SSL が検証されます。 |
--download-migration-logs | 移行された各リポジトリの移行ログをダウンロードします。 移行ログの詳細については、「GitHub Enterprise Importer の移行ログへのアクセス」を参照してください。 |
移行スクリプトの確認
スクリプトを生成したら、ファイルを確認し、必要に応じてスクリプトを編集します。
- 移行したくないリポジトリがある場合は、対応する行を削除するかコメントにします。
- 移行先の Organization でリポジトリに別の名前を使う場合は、対応する
--target-repo
フラグの値を更新します。 - 新しいリポジトリの表示範囲を変更する場合は、対応する
--target-repo-visibility
フラグの値を更新します。 既定では、スクリプトはソース リポジトリと同じ表示範囲を設定します。
リポジトリに 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_ID
: バケットのアクセス キー IDAWS_SECRET_ACCESS_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"
プレースホルダー
上のコマンドのプレースホルダーを次の値に置き換えます。
プレースホルダー | 値 |
---|---|
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 バケットのバケット名 |
追加の引数
引数 | 説明 |
---|---|
--target-api-url TARGET-API-URL | GHE.com に移行する場合は、--target-api-url TARGET-API-URL を追加します。TARGET-API-URL は Enterprise のサブドメインのベース API URL です。 (例: https:/ )。 |
--no-ssl-verify | お使いの GitHub Enterprise Server インスタンス で自己署名証明書または無効な SSL 証明書が使われている場合は、--no-ssl-verify フラグを使います。 このフラグを使うと、GitHub CLI は、ユーザーのインスタンスのみからデータを抽出するときは、SSL 証明書の検証をスキップします。 その他のすべての呼び出しでは、SSL が検証されます。 |
--skip-releases | リポジトリに 10 GB を超えるリリース データがある場合、リリースを移行することはできません。 リリースなしでリポジトリを移行するには、--skip-releases フラグを使います。 |
--target-repo-visibility TARGET-VISIBILITY | リポジトリは、既定では表示範囲が非公開で移行されます。 表示範囲を設定するには、--target-repo-visibility フラグを追加し、private 、public 、または internal を指定します。 マネージド ユーザーを含む Enterprise に移行する場合、パブリック リポジトリは使用できません。 |
移行の中止
移行を取り消す場合は、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 によってストレージ コンテナーに配置されたアーカイブを削除します。 移行が完了したら、コンテナー全体を削除できます。