Edit

3. Start the migration

Azure DevOps Services

After you complete the prerequisites, authenticate into Azure DevOps and start the initial synchronization for your repository. Use the service connection ID you created in the prerequisites when you start the migration.

Note

All steps in this article use the Azure DevOps CLI. The only exception is checking that your self-hosted Linux agent is online, which you can do from the Azure DevOps portal.

Authenticate into Azure DevOps

ELM requires authenticated access to Azure DevOps.

  1. Sign in to the Azure CLI:

    az login

  2. Set your default Azure DevOps organization:

    az devops configure --defaults organization=https://dev.azure.com/myorg

    Tip

    If your local Git remote points to a different organization, add --detect false to all migration commands to prevent autodetection from choosing the wrong organization.

  3. Verify your access:

    az devops project list

  4. Get the repository GUID:

    az repos show --org https://dev.azure.com/<org>
              --project <project>
              --repository <repo-name>
              --query id
              -o tsv

Start the agent

Your self-hosted Linux agent must be online and listening before you start a migration.

  1. Check the agent status in the Azure DevOps portal under Project Settings > Agent pools. Select your pool, open the Agents tab, and confirm the agent shows as Online.

  2. If the agent is offline, sign in to the Linux machine where the agent is installed and change to the agent install directory.

  3. Start the agent interactively:

    ./run.sh

  4. To run the agent as a service so it stays online across reboots:

    sudo ./svc.sh install
sudo ./svc.sh start

For more information, see Run a self-hosted agent in Linux.

(Optional) Validate the repository before you start

Run validation first to identify eligibility problems before any data transfers. After you resolve all problems, the repository is ready to sync. You have 24 hours to start the migration before validation expires. If you miss this window, rerun validation.

  1. Run validation only:

    az devops migrations create --org https://dev.azure.com/<org>
                            --repository-id <repo-guid>
                            --target-repository https://<enterprise>.ghe.com/<org>/<repo>
                            --target-owner-user-id <id>
                            --service-endpoint-id <service-connection-guid>
                            --agent-pool <agent-pool-name>
                            --validate-only

  2. Check validation status:

    az devops migrations status --org https://dev.azure.com/<org>
                            --repository-id <repo-guid>

    For details, see validationIssues and errorMessage in the output. For current thresholds, see the validation checks.

    Important

    Proceeding with unresolved validation errors significantly increases the likelihood that the migration fails later. Fix all errors before you continue.

  3. After validation succeeds, promote to a full migration:

    az devops migrations resume --org https://dev.azure.com/<org>
                            --repository-id <repo-guid>
                            --migration

Start the synchronization

Start the synchronization by running the following command. In --target-repository, <repo> is the GitHub repository name. Choose any available name. It doesn't have to match the Azure DevOps repository name.

az devops migrations create --org https://dev.azure.com/<org>
                            --repository-id <repo-guid>
                            --target-repository https://<enterprise>.ghe.com/<org>/<repo>
                            --target-owner-user-id <id>
                            --agent-pool <agent-pool-name>
                            --service-endpoint-id <service-connection-guid>

Check status:

az devops migrations status --org https://dev.azure.com/<org>
                            --repository-id <repo-guid>

Look for:

  • status — current migration status (Active, Succeeded, Completed, Failed, Suspended)
  • stage — current migration phase (Queued, Validation, Synchronization, Cutover, ReviewForCutover, ReadyForCutover, Migrated)
  • validationIssues — list of precheck failures with error codes and messages
  • errorMessage — details about the failure

For current thresholds, see the validation checks.

Important

Unresolved validation errors significantly increase the risk of migration failure. Fix all errors before you proceed.

During the initial sync:

  • Azure DevOps remains fully writable. Teams continue working normally.
  • GitHub isn't yet the system of record.
  • The target GitHub repository is automatically set to private.

Important

After you start a full migration, you must complete cutover within 21 days. The clock starts when the initial sync begins.

Next step

Monitor the migration

Related content

  • Last updated on