ガイド: Azure DevOpsからGitLabへの移行

Azure DevOpsからGitLabへの移行は困難な作業のように思えるかもしれませんが、適切なアプローチとツールを使用すれば、スムーズかつ効率的に進められます。このガイドでは、Azure DevOpsからGitLabへプロジェクト、リポジトリ、パイプラインを正常に移行するために必要な手順を説明します。

概要

GitLabは、Azure DevOps（ADO）からプロジェクトを移行するためのCongregate(GitLabプロフェッショナルサービス（PS）によって管理）と組み込みのGitリポジトリインポートの両方を提供しています。これらのオプションは、リポジトリごとまたは一括移行をサポートし、Gitコミット履歴、ブランチ、タグを保持します。Congregateとプロフェッショナルサービスのツールを使用すると、Wiki、作業アイテム、CI/CD変数、コンテナイメージ、パッケージ、パイプラインなどの追加アセットもサポートされます（この機能マトリクスを参照）。このガイドを参照すれば、移行を計画・実行し、移行後のフォローアップタスクを完了できます。

ADOからGitLabへ移行する企業は、一般的に複数フェーズのアプローチに従います：

• CongregateまたはGitLabの組み込みリポジトリ移行を使用して、ADOからGitLabにリポジトリを移行します。
• AzureパイプラインからGitLab CI/CDにパイプラインを移行します。
• ボード、作業アイテム、アーティファクトなどの残りのアセットを、GitLabのイシュー、エピック、パッケージレジストリ、コンテナレジストリに移行します。

移行フェーズの概要:

移行の計画

移行を計画するにあたり、次の質問を検討します:

• 移行をいつまでに完了する必要があるか?
• 何が移行されるかを理解しているか?
• 誰が移行を実行するか?
• GitLabでどのような組織構造を望むか?
• 考慮すべき制約、制限、落とし穴はあるか?

タイムラインを決定します。これは移行アプローチを大きく左右します。ADOとGitLabの両プラットフォームに精通したチャンピオンやグループ（アーリーアダプターなど）を特定し、導入を推進してアドバイスを提供してもらいます。

移行が必要なものをインベントリ化:

• リポジトリ、プルリクエスト、コントリビューターの数
• 作業アイテムとパイプラインの数と複雑さ
• リポジトリのサイズと依存関係
• 重要なインテグレーションとRunner要件（特定の機能を持つエージェントプール）

GitLab プロフェッショナルサービスのEvaluateツールを使用して、リポジトリ、PR数、コントリビューターリスト、パイプライン数、作業アイテム、CI/CD変数などを含むAzure DevOps組織全体の完全なインベントリを作成します。GitLabプロフェッショナルサービスチームと連携している場合は、このレポートをエンゲージメントマネージャーまたはテクニカルアーキテクトと共有し、移行計画に役立ててください。

移行のタイミングは、主にプルリクエスト数、リポジトリサイズ、コントリビューション量（PRのコメント、作業アイテムなど）によって決まります。たとえば、PRが少なくコントリビューターが限られた1,000の小規模リポジトリは、数万のPRと数千のコントリビューターを含む少数のリポジトリよりもはるかに高速に移行できます。インベントリデータを使用して作業量を見積もり、本番移行を進める前にテスト実行を計画します。

インベントリを希望のタイムラインと比較し、すべてのリポジトリを一度に移行するか、バッチで移行するかを決定します。チームが同時に移行できない場合は、チームのスケジュールに合わせて移行をバッチ化し、段階的に実行します。たとえば、プロフェッショナルサービスのエンゲージメントでは、複雑さを管理し、GitLabとADOの両方のAPIレート制限を尊重するために、200〜300プロジェクト単位の段階に分割して移行を実施します。

GitLabの組み込みリポジトリインポーターは、Gitリポジトリ（コミット、ブランチ、タグ）を1つずつ移行します。Congregateは、可能な限りプルリクエスト（GitLabではマージリクエストとして知られています）、コメント、関連メタデータを保持するように設計されています。シンプルな組み込みリポジトリインポートは、Gitデータ（履歴、ブランチ、タグ）のみに焦点を当てています。

通常、個別の移行または手動での再作成が必要な項目:

• Azureパイプライン - 同等のGitLab CI/CDパイプラインを作成(CI/CD YAMLまたはCI/CDコンポーネントを参照)。または、CongregateのAIベースのパイプライン変換を使用することを検討してください。
• 作業アイテムとボード - GitLabのイシュー、エピック、イシュー ボードにマッピング。
• アーティファクト、コンテナイメージ(ACR) - GitLabパッケージレジストリまたはコンテナレジストリに移行。
• サービスフックと外部インテグレーション - GitLabで再作成。
• 権限モデルはADOとGitLabで異なります。完全な保持を想定するのではなく、権限マッピングを確認および計画してください。

各ツール（Congregateと組み込みインポート）が何を移行するかを確認し、ニーズに合ったものを選択します。手動で移行または再作成する必要があるデータやインテグレーションのリストを作成します。

誰が移行を実行するか?

移行は通常、GitLabグループオーナーまたはインスタンス管理者、または移行先グループ/プロジェクトに必要な権限を付与された指定の移行担当者によって実行されます。CongregateとGitLabインポートAPIには、Azure DevOpsとGitLabの両方の有効な認証トークンが必要です。

• グループオーナー/管理者が移行を実行するか、特定のチーム/個人に委任アクセスを付与するかを決定します。
• 移行担当者が、選択した移行ツールに必要なスコープ（api/read_repositoryスコープやツール固有の要件など）を持つ個人アクセストークン（Azure DevOpsとGitLab）を正しく設定していることを確認します。
• 小規模なパイロット移行でトークンと権限をテストします。

注: CongregateはADO移行のためにファイルベースのインポート機能を活用し、実行にはインスタンス管理者権限が必要です（ドキュメントを参照）。GitLab.comに移行する場合は、プロフェッショナルサービスの利用を検討してください。詳細については、Professional Services Full Catalogを参照してください。管理者以外のアカウントでは、コントリビューションの帰属を保持できません。

GitLabでどのような組織構造を望むか?

ADO構造をGitLab構造に直接マッピングすることは可能ですが、移行中に構造を合理化および簡素化することをお勧めします。チームがGitLabでどのように作業するかを検討し、コラボレーションとアクセス管理を促進する構造を設計します。ADO構造をGitLab構造にマッピングする方法は次のとおりです。

推奨アプローチ:

• 各ADO組織をGitLabグループ（または少数のグループ）にマッピングし、多数の小さなグループには分割しないでください。ADOチームプロジェクトごとにGitLabグループを作成することは避けてください。移行をGitLab構造を合理化する機会として活用してください。
• サブグループとプロジェクトレベルの権限を使用して、関連リポジトリをグループ化します。
• GitLabグループとグループメンバーシップ（グループとサブグループ）を使用してプロジェクトのセットへのアクセスを管理し、チームプロジェクトごとに1つのグループを作成しないでください。
• GitLabの権限を確認し、SAML Group Linksを検討して、GitLabインスタンス（またはGitLab.comネームスペース）のエンタープライズRBACモデルを実装します。

ADOボードと作業アイテム: 移行の状態

作業アイテムがADOからGitLab Plan（イシュー、エピック、ボード）にどのように移行されるかを理解することが重要です。

• ADOボードと作業アイテムは、GitLabのイシュー、エピック、イシューボードにマッピングされます。ワークフローとボード設定がどのように変換されるかを計画します。
• ADOのエピックと機能は、GitLabのエピックになります。
• その他の作業アイテムタイプ（ユーザーストーリー、タスク、バグなど）は、プロジェクトスコープのイシューになります。
• ほとんどの標準フィールドが保持されます。サポートされている場合、選択したカスタムフィールドを移行できます。
• 親子関係が保持されるため、エピックはすべての関連イシューを参照します。
• プルリクエストへのリンクはマージリクエストリンクに変換され、開発のトレーサビリティが維持されます。

例: 個別の作業アイテムのGitLabイシューへの移行（フィールドの正確性と関係性を含む）:

バッチ処理のガイダンス:

• バッチで移行を実行する必要がある場合は、新しいグループ/サブグループ構造を使用してバッチを定義します（たとえば、ADO組織ごと、または製品領域ごと）。
• インベントリレポートを使用してバッチ選択を推進し、スケールアップする前に各バッチをパイロット移行でテストします。

パイプライン移行

Congregateは最近、Azure DevOpsからGitLab CI/CDへのマルチステージYAMLパイプラインのAI搭載変換を導入しました。この自動変換は、シンプルな単一ファイルパイプラインに最適で、本番環境対応の.gitlab-ci.ymlファイルではなく、動作する出発点を提供するように設計されています。このツールは、機能的に同等のGitLabパイプラインを生成し、その後特定のニーズに合わせて調整および最適化できます。

• Azureパイプライン YAMLを.gitlab-ci.yml形式に自動変換します。
• シンプルな単一ファイルパイプライン設定に最適です。
• 移行を加速するためのボイラープレートを提供し、最終的な本番環境アーティファクトではありません。
• 複雑なシナリオ、カスタムタスク、エンタープライズ要件については、レビューや調整が必要です。
• Azure DevOpsのクラシックリリースパイプラインはサポートしていません — 最初にマルチステージYAMLに変換してください。

リポジトリオーナーは、初期変換後にパイプラインをさらに最適化および強化するために、GitLab CI/CDドキュメントを確認する必要があります。

変換されたパイプラインの例:

# azure-pipelines.yml

trigger:
  - main

variables:
  imageName: myapp

stages:
  - stage: Build
    jobs:
      - job: Build
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - checkout: self

          - task: Docker@2
            displayName: Build Docker image
            inputs:
              command: build
              repository: $(imageName)
              Dockerfile: '**/Dockerfile'
              tags: |
                $(Build.BuildId)

  - stage: Test
    jobs:
      - job: Test
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - checkout: self

          # Example: run tests inside the container
          - script: |
              docker run --rm $(imageName):$(Build.BuildId) npm test
            displayName: Run tests

  - stage: Push
    jobs:
      - job: Push
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - checkout: self

          - task: Docker@2
            displayName: Login to ACR
            inputs:
              command: login
              containerRegistry: '<your-acr-service-connection>'

          - task: Docker@2
            displayName: Push image to ACR
            inputs:
              command: push
              repository: $(imageName)
              tags: |
                $(Build.BuildId)

# .gitlab-ci.yml

variables:
  imageName: myapp

stages:
  - build
  - test
  - push

build:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -t $imageName:$CI_PIPELINE_ID -f $(find . -name Dockerfile) .
  only:
    - main

test:
  stage: test
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker run --rm $imageName:$CI_PIPELINE_ID npm test
  only:
    - main

push:
  stage: push
  image: docker:latest
  services:
    - docker:dind
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  script:
    - docker tag $imageName:$CI_PIPELINE_ID $CI_REGISTRY/$CI_PROJECT_PATH/$imageName:$CI_PIPELINE_ID
    - docker push $CI_REGISTRY/$CI_PROJECT_PATH/$imageName:$CI_PIPELINE_ID
  only:
    - main

最終チェックリスト:

• タイムラインとバッチ戦略を決定します。
• リポジトリ、PR、コントリビューターの完全なインベントリを作成します。
• スコープ（PRとメタデータ vs Gitデータのみ）に基づいて、Congregateまたは組み込みインポートを選択します。
• 誰が移行を実行するかを決定し、トークン/権限が設定されていることを確認します。
• 個別に移行する必要があるアセット（パイプライン、作業アイテム、アーティファクト、フック）を特定し、それらの取り組みを計画します。
• パイロット移行を実行し、結果を検証してから、計画に従ってスケールします。

移行の実行

計画後、トライアル実行から始めて、段階的に移行を実行します。トライアル移行は、組織固有の問題を早期に明らかにし、期間を測定し、結果を検証し、本番環境前にアプローチを微調整する上で役立ちます。

トライアル移行が検証する内容:

• 特定のリポジトリと関連アセットが正常に移行されるかどうか（履歴、ブランチ、タグ。Congregateを使用する場合はMR/コメントも含む）
• 移行先がすぐに使用可能かどうか（権限、Runner、CI/CD変数、インテグレーション）
• スケジュールとステークホルダーの期待値を設定するため、各バッチにかかる時間。

ダウンタイムのガイダンス:

• GitLabの組み込みGitインポートとCongregateは、本質的にダウンタイムを必要としません。
• 本番環境の場合では、ADOの変更を凍結（ブランチ保護または読み取り専用）して、移行中に見逃されたコミット、PR更新、作業アイテムの作成を回避します。
• トライアル実行では凍結は必要なく、いつでも実行できます。

バッチ処理のガイダンス:

• 経過時間を短縮するために、トライアルバッチを連続して実行します。チームは非同期で結果を検証できます。
• 計画したグループ/サブグループ構造を使用してバッチを定義し、APIレート制限を遵守します。

推奨手順:

1. GitLabでトライアル用のテスト先を作成:

• GitLab.com: 専用グループ/ネームスペースを作成（例: my-org-sandbox）
• Self-managed: トップレベルグループまたは必要に応じて別のテストインスタンスを作成

2. 認証の準備:

• 必要なスコープを持つAzure DevOps PAT
• apiとread_repositoryを持つGitLabパーソナルアクセストークン（Congregateで使用されるファイルベースのインポートの場合は管理者アクセスも含む）```suggestion:-0+0
• apiとread_repositoryを持つGitLabパーソナルアクセストークン（Congregateで使用されるファイルベースのインポートの場合は管理者アクセスも含む）

3. トライアル移行の実行:

• リポジトリのみ: GitLabの組み込みインポート（URLによるレポジトリインポート）を使用
• リポジトリ + PR/MRおよび追加アセット: Congregateを使用

4. トライアル後のフォローアップ:

• リポジトリ履歴、ブランチ、タグ、マージリクエスト（移行された場合）、イシュー/エピック（移行された場合）、ラベル、関係性を確認します。
• 権限/ロール、保護ブランチ、必要な承認、Runner/タグ、変数/シークレット、インテグレーション/Webhookを確認します。
• パイプライン（.gitlab-ci.yml）または（該当する場合は）変換されたパイプラインを検証します。

5. ユーザーに機能とデータの正確性を検証してもらいます。
6. トライアル中に発見された問題を解決し、実行手順を更新します。
7. ネットワークとセキュリティ:

• 移行先の環境がIP許可リストを使用している場合、インポートが成功するように、移行ホストと必要なRunner/インテグレーションのIPを追加します。

8. 本番環境への移行は段階的に実行:

• 各段階で、ADOで変更凍結を実施します。
• 進捗とログを監視します。レート制限に達した場合は、再試行するか、バッチサイズを調整します。

9. オプション: 完了後、サンドボックスグループを削除またはアーカイブします。

GitLabとAzure DevOpsの用語リファレンス