GitHub Enterprise Importer
を使ったリポジトリの移行について
GitHub CLI または API を使って、移行を実行できます。
GitHub CLI を使うと移行プロセスが簡単になるので、ほとんどのお客様に推奨されます。 カスタマイズのニーズが高い熟練したお客様は、API を使って、GitHub Enterprise Importer との独自の統合を構築できます。
Note
移行しているリポジトリに、受信リポジトリが一致しないルールセットがある場合、この移行はブロックされます。 これらのルールセットをバイパスして移行を許可するには、ターゲット組織のすべてのデプロイ キーにルールセット バイパスを適用します。
リポジトリのルールセットは、組織レベルで設定できます。 受信リポジトリがこれらのルールセットのいずれにも一致しない場合は、それぞれにデプロイ キーバイパスを使用する必要があります。 「組織内のリポジトリのルールセットを作成する」をご覧ください。
前提条件
- 移行の試験的実行を行い、そのすぐ後で運用環境の移行を完了することを強くお勧めします。 試験的実行について詳しくは、「Azure DevOps から GitHub Enterprise クラウドへの移行の概要」をご覧ください。
- 移行されるデータと、Importer の既知のサポート制限事項を理解していることを確認します。 詳しくは、「Azure DevOps から GitHub Enterprise クラウドへの移行について」をご覧ください。
- 必須ではありませんが、運用環境の移行の間は作業を停止することをお勧めします。 Importer は差分移行をサポートしていないため、移行中に発生した変更は移行されません。 運用環境の移行の間に作業を停止しない場合は、これらの変更を手動で移行する必要があります。
- GitHub の移行先の Organization では、Organization 所有者であるか、移行者ロールを持っている必要があります。 移行者ロールについて詳しくは、「Azure DevOps からの移行のアクセスの管理」をご覧ください。
手順 0: GitHub GraphQL API を使う準備をする
GraphQL クエリを作成するには、独自のスクリプトを記述するか、Insomnia などの HTTP クライアントを使う必要があります。
認証方法など、GitHub GraphQL API での作業の始め方について詳しくは、「GraphQLでの呼び出しの作成」をご覧ください。
手順 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 を指定する必要があります。
移行ソースは ADO 組織です。
createMigrationSource
のミューテーション
mutation createMigrationSource($name: String!, $ownerId: ID!) {
createMigrationSource(input: {name: $name, url: "https://dev.azure.com", ownerId: $ownerId, type: AZURE_DEVOPS}) {
migrationSource {
id
name
url
type
}
}
}
注: type
には必ず AZURE_DEVOPS
を使ってください。
クエリ変数 | 説明 |
---|---|
name | 移行元の名前。 この名前は自分の参照用であるため、任意の文字列を使用できます。 |
ownerId | GitHub Enterprise Cloud での Organization の Organization ID。 |
createMigrationSource
応答
{
"data": {
"createMigrationSource": {
"migrationSource": {
"id": "MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA",
"name": "Azure Devops Source",
"url": "https://dev.azure.com",
"type": "AZURE_DEVOPS"
}
}
}
}
この例では、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://dev.azure.com/{organization}/{project}/_git/{repository} 形式を使ったソース リポジトリの URL。 |
personal access token の要件については、「Azure DevOps からの移行のアクセスの管理」をご覧ください。
次のステップでは、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: ADO2GH extension of the GitHub CLI をインストールする
これが初めての移行の場合は、ADO2GH extension of the GitHub CLI をインストールする必要があります。 GitHub CLI の詳細については、「GitHub CLI について」を参照してください。
または、github/gh-ado2gh
リポジトリの「リリース ページ」からスタンドアロン バイナリをダウンロードすることもできます。 このバイナリは、gh
プレフィックスなしで直接実行できます。
-
GitHub CLI をインストールします。 GitHub CLI のインストール手順については、GitHub CLI リポジトリを参照してください。
注: GitHub CLI のバージョン 2.4.0 以降が必要です。
gh --version
コマンドを使って、インストールされているバージョンを確認できます。 -
ADO2GH extension をインストールします。
Shell gh extension install github/gh-ado2gh
gh extension install github/gh-ado2gh
ADO2GH extension に関するヘルプが必要なときはいつでも、コマンドで --help
フラグを使用できます。 たとえば、gh ado2gh --help
とすると使用可能なすべてのコマンドの一覧が表示され、gh ado2gh migrate-repo --help
とすると migrate-repo
コマンドで使用できるすべてのオプションの一覧が表示されます。
手順 2: ADO2GH extension of the GitHub CLI を更新する
ADO2GH extension of the GitHub CLI は毎週更新されます。 最新バージョンを確実に使うため、拡張機能を更新してください。
gh extension upgrade github/gh-ado2gh
gh extension upgrade github/gh-ado2gh
手順 3: 環境変数を設定する
ADO2GH extension を使って GitHub Enterprise Cloud に移行するには、その前に、移行元と移行先の Organization にアクセスできる personal access token を作成してから、personal access token を環境変数として設定する必要があります。
-
GitHub Enterprise Cloud 上の移行先 Organization に対して認証を行う personal access token (classic) を作成して記録し、トークンがすべての要件を満たしていることを確認します。 詳しくは、「Azure DevOps からの移行のアクセスの管理」を参照してください。
-
移行元Azure DevOpsの Organization に対して認証を行う personal access token を作成して記録し、このトークンが要件をすべて満たしていることを確認します。 詳しくは、「Azure DevOps からの移行のアクセスの管理」を参照してください。
-
personal access token に対する環境変数を設定します。次のコマンドの TOKEN は、上で記録した personal access token に置き換えます。 移行先の Organization には
GH_PAT
を使い、移行元の Organization にはADO_PAT
を使います。-
ターミナルを使っている場合は、
export
コマンドを使います。Shell export GH_PAT="TOKEN" export ADO_PAT="TOKEN"
export GH_PAT="TOKEN" export ADO_PAT="TOKEN"
-
PowerShell を使っている場合は、
$env
コマンドを使います。Shell $env:GH_PAT="TOKEN" $env:ADO_PAT="TOKEN"
$env:GH_PAT="TOKEN" $env:ADO_PAT="TOKEN"
-
手順 4: 移行スクリプトを生成する
複数のリポジトリを GitHub Enterprise Cloud に一度に移行したい場合は、GitHub CLI を使って移行スクリプトを生成します。 結果のスクリプトには、リポジトリごとに 1 つの移行コマンドのリストが含まれます。
注: スクリプトを生成すると、PowerShell スクリプトが出力されます。 ターミナルを使っている場合は、.ps1
ファイル拡張子を持つスクリプトを出力し、Mac または Linux 用の PowerShell をインストールして実行する必要があります。
1 つのリポジトリを移行する場合は、次のステップに進んでください。
移行スクリプトの生成
移行スクリプトを生成するには、gh ado2gh generate-script
コマンドを実行します。
gh ado2gh generate-script --ado-org SOURCE --github-org DESTINATION --output FILENAME
gh ado2gh generate-script --ado-org SOURCE --github-org DESTINATION --output FILENAME
パイプラインの再調整、チームの作成、Azure Boards 統合の構成など、スクリプトに新しい機能を追加するには、--all
フラグを追加します。
移行された各リポジトリの移行ログをダウンロードするスクリプトが必要な場合は、--download-migration-logs
フラグを追加します。 移行ログについて詳しくは、「GitHub Enterprise Importer の移行ログへのアクセス」をご覧ください。
上のコマンドのプレースホルダーを次の値に置き換えます。
プレースホルダー | 値 |
---|---|
SOURCE | 移行元の Organization の名前 |
DESTINATION | 移行先の Organization の名前 |
FILENAME | 結果の移行スクリプトのファイル名 ターミナルを使っている場合は、生成されたスクリプトの実行に PowerShell が必要なので、 .ps1 ファイル拡張子を使います。 Mac 用または Linux 用の PowerShell をインストールできます。 |
移行スクリプトの確認
スクリプトを生成したら、ファイルを確認し、必要に応じてスクリプトを編集します。
- 移行したくないリポジトリがある場合は、対応する行を削除するかコメントにします。
- 移行先の Organization でリポジトリに別の名前を使う場合は、対応する
--target-repo
フラグの値を更新します。 - 新しいリポジトリの表示範囲を変更する場合は、対応する
--target-repo-visibility
フラグの値を更新します。 既定では、スクリプトはソース リポジトリと同じ表示範囲を設定します。
ADO2GH の拡張機能としてではなく、スタンドアロン バイナリとして GitHub CLI をダウンロードした場合は、生成されたスクリプトを更新して、gh ado2gh
ではなくバイナリを実行する必要があります。
手順 5: リポジトリを移行する
移行スクリプトを使って複数のリポジトリを移行すること、または gh ado2gh migrate-repo
コマンドを使って 1 つのリポジトリを移行することができます。
複数のリポジトリを移行する
複数のリポジトリを移行するには、上で生成したスクリプトを実行します。 次のコマンドの FILENAME を、スクリプトの生成時に指定したファイル名に置き換えます。
-
ターミナルを使っている場合は、
./
を使います。Shell ./FILENAME
./FILENAME
-
PowerShell を使っている場合は、
.\
を使います。Shell .\FILENAME
.\FILENAME
1 つのリポジトリを移行する
1 つのリポジトリを移行するには、gh ado2gh migrate-repo
コマンドを使います。
gh ado2gh migrate-repo --ado-org SOURCE --ado-team-project TEAM-PROJECT --ado-repo CURRENT-NAME --github-org DESTINATION --github-repo NEW-NAME
gh ado2gh migrate-repo --ado-org SOURCE --ado-team-project TEAM-PROJECT --ado-repo CURRENT-NAME --github-org DESTINATION --github-repo NEW-NAME
上のコマンドのプレースホルダーを次の値に置き換えます。
プレースホルダー | 値 |
---|---|
SOURCE | 移行元の Organization の名前 |
CURRENT-NAME | 移行するリポジトリの名前 |
DESTINATION | 移行先の Organization の名前 |
NEW-NAME | 移行されたリポジトリに設定する名前 |
TEAM-PROJECT | 移行するリポジトリのチーム プロジェクトの名前 |
移行を取り消す場合は、MIGRATION-ID を abort-migration
返された( migrate-repo
から)ID に置き換えて、コマンドを使用します。
gh ado2gh abort-migration --migration-id MIGRATION-ID
gh ado2gh abort-migration --migration-id MIGRATION-ID
手順 6: 移行を検証し、エラー ログを確認する
移行が完了したら、移行ログを確認することをお勧めします。 詳しくは、「GitHub Enterprise Importer の移行ログへのアクセス」を参照してください。
移行したリポジトリで健全性チェックを確認することをお勧めします。