背景
GitHub Copilot の Coding Agent や Review 機能を使いたい！ってなって、Azure DevOps から GitHub への移行を行った際の記録。
Azure DevOps はレガシーってほど古いわけじゃないんですが、GitHub と比べると以下の点が不満だった為に、今後を見据えて移行しました。
- Pipelines のコマンドが GitHub Actions に比べて弱い。
- 例）az-cli が直接使えない
- GitHub Copilot の機能を直接使えない
- 例）Coding Agent, Reviewer
- MSさんが力を入れているように感じられず、今後に不安
おすすめの読者
Azure DevOps を使っていて、GitHub Copilot を契約している方
移行は簡単ですし、Copilot がより便利に使えるようになるので 😁😁😁
概要
GitHub が公式で提供している gh-ado2gh 拡張機能を使えば、コマンド一発で移行できる。
移行できないものもあるが、今回のプロジェクトでは特に問題ないと判断して実施。詳細は後述
- GitHub CLI (
gh) のインストール -
gh-ado2gh拡張機能の追加 - Personal Access Token (PAT) の準備（DevOps & GitHub)
- 移行コマンド実行
- 履歴もコミットもそのまま移行完了
- アカウント情報の紐づけ（マネキン）
GitHub Enterprise Importer とは？
GitHub が提供する公式の移行ツール。Azure DevOps、Bitbucket Server、GitHub.com などから GitHub Enterprise Cloud へリポジトリを移行できる。コミット履歴やメタデータを保持したまま移行可能。
詳細
1. GitHub CLI のインストール
まずは GitHub CLI (gh) をインストールする。
Windows の場合、winget で一発。
winget install --id GitHub.cli
GitHub CLI とは？
GitHub の公式コマンドラインツール。リポジトリ操作、Issue 管理、Pull Request 作成などを CLI で実行できる。移行ツールの gh-ado2gh は、この GitHub CLI の拡張機能として動作する。
インストール後、バージョン確認。
gh --version
バージョン 2.4.0 以降が必要なので、古い場合はアップデートする。
GitHub CLI は、GitHub との認証や API 操作を簡単に行えるツールです。リポジトリのクローン、Issue の作成、Pull Request のマージなど、様々な操作をコマンドラインから実行できます。
2. gh-ado2gh 拡張機能のインストール
次に、Azure DevOps から GitHub への移行専用の拡張機能をインストール。
gh extension install github/gh-ado2gh
拡張機能は定期的に更新されるので、最新版にアップデート。
gh extension upgrade github/gh-ado2gh
3. Personal Access Token (PAT) の準備
移行には、移行元（Azure DevOps）と移行先（GitHub）の両方で PAT が必要。
Azure DevOps の PAT
Azure DevOps にサインインして、ユーザー設定から「個人用アクセス トークン」を選択。
必要なスコープ：
- Code (Read): ソースコードの読み取り
- Work Items (Read): 作業項目の読み取り
- Identity (Read): ユーザー情報の読み取り
PAT の有効期限
Azure DevOps の PAT には有効期限を設定する必要がある。移行作業が完了するまでの期間を考慮して設定すること。移行後は速やかに取り消すことを推奨。
個人用アクセス トークン (PAT) は、Azure DevOps に認証するための代替パスワードとして機能します。この PAT は、ユーザーを識別し、アクセスのアクセシビリティとスコープを決定します。パスワードと同じレベルの注意を払って、PAT を扱います。
GitHub の PAT
GitHub にサインインして、Settings → Developer settings → Personal access tokens → Tokens (classic) から作成。
classic としてるのは、今回のOrganizationでは Classic としていたため
必要なスコープ：
- repo: リポジトリへのフルアクセス
- admin:org: Organization の管理（移行先が Organization の場合）
- workflow: GitHub Actions ワークフローの管理
個人用アクセス トークンは、GitHub API または コマンド ラインを使うときに GitHub への認証でパスワードの代わりに使うことができます。
環境変数に設定
作成した PAT を環境変数にセット。
PowerShell の場合：
$env:ADO_PAT="<Azure DevOps の PAT>"
$env:GH_PAT="<GitHub の PAT>"
PAT の取り扱い注意
PAT はパスワードと同等の権限を持つので注意
4. 移行コマンド実行
準備が整ったら、移行コマンドを実行。
単一リポジトリの移行
gh ado2gh migrate-repo `
--ado-org <Azure DevOps 組織名> `
--ado-team-project <チームプロジェクト名> `
--ado-repo <リポジトリ名> `
--github-org <GitHub Organization 名> `
--github-repo <新しいリポジトリ名>
例：
gh ado2gh migrate-repo `
--ado-org contoso `
--ado-team-project MyProject `
--ado-repo MyRepo `
--github-org contoso-github `
--github-repo my-repo
複数リポジトリの移行
複数のリポジトリを一括移行したい場合は、移行スクリプトを生成できるらしいが、今回は不要だったので未使用。情報として記録のみ
gh ado2gh generate-script `
--ado-org <Azure DevOps 組織名> `
--github-org <GitHub Organization 名> `
--output migration-script.ps1
生成されたスクリプトを確認・編集してから実行。
.\migration-script.ps1
移行できるデータ vs 出来ないデータ
移行されるデータ
GitHub Enterprise Importer は以下のデータを移行する：
- Git リポジトリのソースコード
- コミット履歴
- ブランチ
- タグ
- Git LFS (Large File Storage) オブジェクト
移行されないデータ（重要）
以下のデータは移行されないので注意：
- Pull Requests（プルリクエスト）: オープン・クローズ問わず移行されない
- Work Items（作業項目）: Azure Boards のタスク、バグ、ユーザーストーリーなど
- Pipelines（パイプライン）: Azure Pipelines の CI/CD 定義（GitHub Actions への手動移行が必要）
- Test Plans（テスト計画）: テストケースや実行履歴
- Wiki: リポジトリ Wiki の内容
- Release Notes（リリースノート）: Azure DevOps のリリース情報
- Service Hooks（サービスフック）: 外部サービスとの連携設定
- Extensions（拡張機能）: インストール済みの拡張機能
GitHub Enterprise Importer は、リポジトリのソース コードとコミット履歴をインポートします。問題やプル要求など、関連する他のデータはホスティング サービスからインポートされません。
移行されないデータの詳細については、Azure DevOps から GitHub Enterprise Cloud への移行についてを参照。
5. 移行状態の確認
移行が完了すると、GitHub 上の移行先リポジトリに「Migration Log」という Issue が自動作成される。
この Issue には、移行のログや警告、エラーが記録されているので、必ず確認する。
6. マネキン（仮ユーザー）の対応
Azure DevOps のユーザーが GitHub アカウントと紐付いていない場合、「マネキン（mannequin）」として登録される。
マネキンは仮のユーザーアカウントで、コミット履歴には表示されるが、実際の GitHub ユーザーではない。
マネキンとは？
移行元のユーザーが GitHub に存在しない場合に作成される仮ユーザー。コミット履歴やメタデータを保持するために使用される。本人が GitHub アカウントを取得後、管理者が「reclaim（反映）」操作で履歴を本人に紐付けできる。
マネキンを本人に紐付ける
本人が GitHub アカウントを取得したら、以下のコマンドで紐付け。
今回は、GUIで簡単に紐づけしたので、コマンドは使ってないが、大量にある場合には以下のような感じでやれるみたい
gh api `
--method POST `
-H "Accept: application/vnd.github+json" `
/repos/<ORG>/<REPO>/mannequins/<MANNEQUIN_ID>/reclaim `
-f "mapped_user_id=<USER_ID>"
マネキンの反映により、移行されたコミット履歴と GitHub メタデータの所有権を、プレースホルダーのマネキン ユーザーから、組織のメンバーである実際のユーザーに属するようにすることができます。
— マネキンの反映
7. 移行後の確認事項
移行完了後、以下を確認する。
- コミット履歴が正しく移行されているか
- ブランチ・タグが揃っているか
-
.gitignoreや.gitattributesなどの設定ファイルが移行されているか - GitHub Actions ワークフロー（必要に応じて新規作成）
- ブランチ保護ルールの再設定
- チームメンバーへのアクセス権限設定
あとがき
gh-ado2gh を使えば、Azure DevOps から GitHub への移行が驚くほど簡単だった。
コマンド一発でコミット履歴もそのまま移行できるし、公式ツールだから安心感もある。
移行後は GitHub Copilot の Coding Agent や Review 機能がフル活用できるようになったのが嬉しい
ただ、調子に乗って使いまくったら、以下のようなことになったんですけどね 
Azure Pipelines を使っている場合は GitHub Actions への移行も必要
とはいえ、公式対応されているコマンドが増えるのでめっちゃ楽になりました