GitHub Enterprise Importer
を使ったリポジトリの移行について
GitHub Enterprise Cloud への移行には、GitHub.com のアカウント間での移行のほか、データ所在地が を採用している場合はエンタープライズの GHE.com のサブドメインへの移行も含まれます。
GitHub CLI または API を使って、移行を実行できます。
GitHub CLI を使うと移行プロセスが簡単になるので、ほとんどのお客様に推奨されます。 カスタマイズのニーズが高い熟練したお客様は、API を使って、GitHub Enterprise Importer との独自の統合を構築できます。
前提条件
- 移行の試験的実行を行い、そのすぐ後で運用環境の移行を完了することを強くお勧めします。 試験的実行について詳しくは、「GitHub 製品間の移行に関する概要」をご覧ください。
- 移行されるデータと、Importer の既知のサポート制限事項を理解していることを確認します。 詳しくは、「GitHub 製品間の移行について」をご覧ください。
- 必須ではありませんが、運用環境の移行の間は作業を停止することをお勧めします。 Importer は差分移行をサポートしていないため、移行中に発生した変更は移行されません。 運用環境の移行の間に作業を停止しない場合は、これらの変更を手動で移行する必要があります。
- ユーザーは、移行元 Organization と移行先 Organization の両方で Organization の所有者である、または移行者ロールが付与されている必要があります。 詳しくは、「GitHub 製品間の移行のためのアクセスの管理」を参照してください。
手順 0: GitHub GraphQL API を使う準備をする
GraphQL クエリを作成するには、独自のスクリプトを記述するか、Insomnia などの HTTP クライアントを使う必要があります。
認証方法など、GitHub GraphQL API での作業の始め方について詳しくは、「GraphQLでの呼び出しの作成」をご覧ください。
すべての GraphQL クエリを、移行先に送信します。 データ所在地付き GitHub Enterprise Cloud に移行する場合は、GHE.com のエンタープライズのサブドメインのエンドポイントにクエリを送信してください。
手順 1: 移行先のownerId
を取得する
GitHub Enterprise Cloud の Organization 所有者として、GetOrgInfo
クエリを使って、移行されたリポジトリを所有する Organization の ownerId
(Organization ID とも呼ばれます) を取得します。 移行先を識別するには、ownerId
が必要です。
GetOrgInfo
クエリ
query(
$login: String!
){
organization (login: $login)
{
login
id
name
databaseId
}
}
クエリ変数 | 説明 |
---|---|
login | Organization の名前。 |
GetOrgInfo
の応答
{
"data": {
"organization": {
"login": "Octo",
"id": "MDEyOk9yZ2FuaXphdGlvbjU2MTA=",
"name": "Octo-org",
"databaseId": 5610
}
}
}
この例では、MDEyOk9yZ2FuaXphdGlvbjU2MTA=
が Organization ID つまり ownerId
であり、次のステップでそれを使います。
手順 2: 移行元の場所を特定する
createMigrationSource
クエリを使って、移行元を設定できます。 GetOrgInfo
クエリで収集した ownerId
つまり Organization ID を指定する必要があります。
移行元は、GitHub.com 上の Organization です。
createMigrationSource
ミューテーション
mutation createMigrationSource($name: String!, $ownerId: ID!) {
createMigrationSource(input: {name: $name, url: "https://github.com", ownerId: $ownerId, type: GITHUB_ARCHIVE}) {
migrationSource {
id
name
url
type
}
}
}
Note
type
には GITHUB_ARCHIVE
を使用するようにしてください。
クエリ変数 | 説明 |
---|---|
name | 移行元の名前。 この名前は自分の参照用であるため、任意の文字列を使用できます。 |
ownerId | GitHub Enterprise Cloud での Organization の Organization ID。 |
createMigrationSource
応答
{
"data": {
"createMigrationSource": {
"migrationSource": {
"id": "MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA",
"name": "GitHub.com Source",
"url": "https://github.com",
"type": "GITHUB_SOURCE"
}
}
}
}
この例では、MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA
が移行元 ID であり、次の手順で使います。
手順 3: リポジトリの移行を開始する
移行を始める、1 つのリポジトリとそれに付随するデータが、ユーザーが指定した新しい GitHub リポジトリに移行されます。
同じ移行元 Organization から複数のリポジトリを一度に移動したい場合は、複数の移行をキューに登録できます。 同時に最大 5 つのリポジトリの移行を実行できます。
startRepositoryMigration
ミューテーション
mutation startRepositoryMigration (
$sourceId: ID!,
$ownerId: ID!,
$sourceRepositoryUrl: URI!,
$repositoryName: String!,
$continueOnError: Boolean!,
$accessToken: String!,
$githubPat: String!,
$targetRepoVisibility: String!
){
startRepositoryMigration( input: {
sourceId: $sourceId,
ownerId: $ownerId,
repositoryName: $repositoryName,
continueOnError: $continueOnError,
accessToken: $accessToken,
githubPat: $githubPat,
targetRepoVisibility: $targetRepoVisibility
sourceRepositoryUrl: $sourceRepositoryUrl,
}) {
repositoryMigration {
id
migrationSource {
id
name
type
}
sourceUrl
}
}
}
クエリ変数 | 説明 |
---|---|
sourceId | createMigrationSource ミューテーションから返された移行元の id 。 |
ownerId | GitHub Enterprise Cloud での Organization の Organization ID。 |
repositoryName | GitHub Enterprise Cloud 上で Organization が所有するどのリポジトリでも現在使われていない一意のカスタム リポジトリ名。 移行が完了または停止すると、このリポジトリにエラー ログ issue が作成されます。 |
continueOnError | 移行の失敗を引き起こさないエラーが発生したときに移行を続行できるようにする移行設定。 true または false である必要があります。 Importer が Git ソースを移動できない場合、または Importer が接続を失い、移行を完了するために再接続できない場合を除き、移行が続けられるように、continueOnError を true に設定することを強くお勧めします。 |
githubPat | GitHub Enterprise Cloud 上の移行先 Organization の personal access token。 |
accessToken | 移行元の personal access token。 |
targetRepoVisibility | 新しいリポジトリの可視性。 private 、public 、または internal にする必要があります。 設定されていない場合、リポジトリはプライベートとして移行されます。 |
sourceRepositoryUrl | https://github.com/{organization}/{repository} 形式を使ったソース リポジトリの URL。 |
personal access token の要件については、「GitHub 製品間の移行のためのアクセスの管理」をご覧ください。
次のステップでは、startRepositoryMigration
ミューテーションから返された移行 ID を使って、移行の状態を調べます。
手順 4: 移行の状態を確認する
移行エラーを検出し、移行が行われていることを確認するには、getMigration
クエリを使って移行の状態を調査できます。 また、getMigrations
を使うと、複数の移行の状態を調べることもできます。
getMigration
クエリから返される状態を調べて、移行が queued
、in progress
、failed
、または completed
であるかどうかを確認できます。 移行が失敗した場合、Importer によってエラーの原因が示されます。
getMigration
クエリ
query (
$id: ID!
){
node( id: $id ) {
... on Migration {
id
sourceUrl
migrationSource {
name
}
state
failureReason
}
}
}
クエリ変数 | 説明 |
---|---|
id | startRepositoryMigration ミューテーションが返した移行の id 。 |
手順 5: 移行を検証し、エラー ログを確認する
移行を完了するには、"移行ログ" の issue を確認することをお勧めします。 この issue は、移行先リポジトリの GitHub に作成されます。
最後に、移行したリポジトリで健全性チェックを確認することをお勧めします。
手順 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: 移行スクリプトを生成する
複数のリポジトリを GitHub Enterprise Cloud に一度に移行したい場合は、GitHub CLI を使って移行スクリプトを生成します。 結果のスクリプトには、リポジトリごとに 1 つの移行コマンドのリストが含まれます。
Note
スクリプトを生成すると、PowerShell スクリプトが出力されます。 ターミナルを使っている場合は、.ps1
ファイル拡張子を持つスクリプトを出力し、Mac または Linux 用の PowerShell をインストールして実行する必要があります。
1 つのリポジトリを移行する場合は、次のステップに進んでください。
移行スクリプトの生成
移行スクリプトを生成するには、gh gei generate-script
コマンドを実行します。
gh gei generate-script --github-source-org SOURCE --github-target-org DESTINATION --output FILENAME
gh gei generate-script --github-source-org SOURCE --github-target-org DESTINATION --output FILENAME
GEI の拡張機能としてではなく、スタンドアロン バイナリとして GitHub CLI をダウンロードした場合は、生成されたスクリプトを更新して gh gei
ではなくバイナリを実行する必要があります。
プレースホルダー
上のコマンドのプレースホルダーを次の値に置き換えます。
プレースホルダー | 値 |
---|---|
SOURCE | 移行元の Organization の名前 |
DESTINATION | 移行先の Organization の名前 |
FILENAME | 結果の移行スクリプトのファイル名 ターミナルを使っている場合は、生成されたスクリプトの実行に PowerShell が必要なので、 .ps1 ファイル拡張子を使います。 Mac 用または Linux 用の PowerShell をインストールできます。 |
追加の引数
引数 | 説明 |
---|---|
--target-api-url TARGET-API-URL | GHE.com に移行する場合は、--target-api-url TARGET-API-URL を追加します。TARGET-API-URL は Enterprise のサブドメインのベース API URL です。 (例: https://api.octocorp.ghe.com )。 |
--download-migration-logs | 移行された各リポジトリの移行ログをダウンロードします。 移行ログについて詳しくは、「GitHub Enterprise Importer の移行ログへのアクセス」をご覧ください。 |
移行スクリプトの確認
スクリプトを生成したら、ファイルを確認し、必要に応じてスクリプトを編集します。
- 移行したくないリポジトリがある場合は、対応する行を削除するかコメントにします。
- 移行先の Organization でリポジトリに別の名前を使う場合は、対応する
--target-repo
フラグの値を更新します。 - 新しいリポジトリの表示範囲を変更する場合は、対応する
--target-repo-visibility
フラグの値を更新します。 既定では、スクリプトはソース リポジトリと同じ表示範囲を設定します。
リポジトリに 10 GB を超えるリリース データがある場合、リリースを移行することはできません。 リリースなしでリポジトリを移行するには、--skip-releases
フラグを使います。
GEI の拡張機能としてではなく、スタンドアロン バイナリとして GitHub CLI をダウンロードした場合は、生成されたスクリプトを更新して gh gei
ではなくバイナリを実行する必要があります。
手順 5: リポジトリを移行する
移行スクリプトを使って複数のリポジトリを移行すること、または gh gei migrate-repo
コマンドを使って 1 つのリポジトリを移行することができます。
複数のリポジトリを移行する
複数のリポジトリを移行するには、上で生成したスクリプトを実行します。 次のコマンドの FILENAME を、スクリプトの生成時に指定したファイル名に置き換えます。
-
ターミナルを使っている場合は、
./
を使います。Shell ./FILENAME
./FILENAME
-
PowerShell を使っている場合は、
.\
を使います。Shell .\FILENAME
.\FILENAME
1 つのリポジトリを移行する
1 つのリポジトリを移行するには、gh gei migrate-repo
コマンドを使います。
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME
プレースホルダー
上のコマンドのプレースホルダーを次の値に置き換えます。
プレースホルダー | 値 |
---|---|
SOURCE | 移行元の Organization の名前 |
CURRENT-NAME | 移行するリポジトリの名前 |
DESTINATION | 移行先の Organization の名前 |
NEW-NAME | 移行されたリポジトリに設定する名前 |
追加の引数
引数 | 説明 |
---|---|
--target-api-url TARGET-API-URL | GHE.com に移行する場合は、--target-api-url TARGET-API-URL を追加します。TARGET-API-URL は Enterprise のサブドメインのベース API URL です。 (例: https://api.octocorp.ghe.com )。 |
--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
手順 6: 移行を検証し、エラー ログを確認する
移行が完了したら、移行ログを確認することをお勧めします。 詳しくは、「GitHub Enterprise Importer の移行ログへのアクセス」を参照してください。
移行したリポジトリで健全性チェックを確認することをお勧めします。