3. Start the migration

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
   

1. Sign in to your Azure DevOps organization at https://dev.azure.com/<org>.
2. Open the target project, and then select Project settings.
3. Select Repositories and confirm the repository you plan to migrate is present.
4. Keep the portal open so you can verify agent status later under Project settings > Agent pools.

Start with this base command for every migration:

az devops migrations create --org https://dev.azure.com/<org>
                            --repository-id <repo-guid>
                            --target-repository https://github.com/<org>/<repo>
                            --github-token <github-pat>
                            --service-endpoint-id <service-connection-guid>
                            --agent-pool <agent-pool-name>

In --target-repository, <repo> is the GitHub repository name. Choose any available name. It doesn't need to match the Azure DevOps repository name.

Add optional parameters based on your migration scenario:

Check migration 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

1. In your project, open Project settings.
2. Under Repos, select Migration to GitHub.
3. Select Start a new migration.
4. Choose one or more repositories to migrate, and then select Next.
5. On the migration details page, provide the following values:
   • Migrate action: Select either Migrate selected repositories after validation or Run validation and migrate later.
   • Target repository: Enter the GitHub repository URL in the format https://<enterpriseUrl>/<orgname>/<repo>.
   • GitHub token: Paste your GitHub personal access token.
   • Customize target repository names for all selected repos (optional): Add a prefix and/or suffix. Don't use spaces in repository names.
   • Service connection: Select the GitHub service connection created in prerequisites.
   • Agent pool: Select the self-hosted Linux agent pool where your migration agent is running.
   • Create a Boards connection (optional): Select if you want ELM to create a Boards connection.
   • Automatically discover and rewire pipelines (optional): Select to use pipeline rewiring.
   • Pipeline service connection (optional): Select the pipeline service connection created in prerequisites.
6. Select Run validation or Start migration, based on the migrate action you selected.
7. Open the migration details and confirm validation is running.

1. Start sync within 24 hours after validation succeeds:

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

2. Recheck status:

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

1. In your Azure DevOps project, go to Project settings > Repos > Migration to GitHub.
2. Open the migration that completed validation successfully.
3. Select Start sync to promote validation to full synchronization.
4. Confirm the migration status changes to the synchronization stage.

1. Find the pipeline definition IDs that reference the migrating repository.

   az devops migrations pipelines list reports only the pipelines that are already enrolled in rewiring and their rewiring status. Before you submit any pipelines, it returns an empty result, so you can't use it to discover candidate pipelines. To find the definition IDs to rewire, list the pipelines that build from the source repository:

   az pipelines list --org $org \
                     --project $project \
                     --repository $rid \
                     --repository-type tfsgit \
                     --query "[].{id:id, name:name}" -o table
   

   Use the id values from the output as the --pipeline-ids in the next step.

   Note

   az pipelines list --repository returns only pipelines whose default trigger repository is the source repository. A pipeline that references the repository through a resource, template, or checkout step (rather than as its primary repository) might not appear here. Include those definition IDs as well if you know they depend on the migrating repository.

2. Submit selected pipeline definition IDs for rewiring (maximum 200 IDs per request):

   az devops migrations pipelines submit --org $org \
                                        --repository-id $rid \
                                        --pipeline-ids 42 43 44 \
                                        --service-connection-id $scid
   

   --service-connection-id is optional if you already attached a connection through --pipeline-service-connection-id in migrations create or a previous pipelines update --service-connection-id.

3. If a pipeline references other repositories, map each source repository to its GitHub target:

   az devops migrations pipelines submit --org $org \
                                        --repository-id $rid \
                                        --pipeline-ids 42 43 44 \
                                        --service-connection-id $scid \
                                        --repository-mapping aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa=<GH_ORG>/shared-templates \
                                        --repository-mapping bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb=<GH_ORG>/another-repo
   

   Format: --repository-mapping <sourceRepoId>=<targetOwner>/<targetRepo> (repeatable).

4. Monitor and adjust the pipeline set:

   az devops migrations pipelines list --org $org --repository-id $rid -o table
   

   After you submit pipelines, this command lists each enrolled pipeline and its rewiring status:

   Column	Meaning
   DefinitionId	Pipeline definition ID
   Name	Pipeline name (falls back to the YAML filename if the name isn't available yet)
   Classification	How the pipeline references the repository
   Status	Current rewiring state of the pipeline
   ErrorMessage	Failure detail when the pipeline is in a failed state

   az devops migrations pipelines update --org $org \
                                        --repository-id $rid \
                                        --add-ids 50 51 \
                                        --remove-ids 42 \
                                        --retry-ids 43 \
                                        --service-connection-id $scid
   

   • --add-ids: add more pipelines.
   • --remove-ids: remove pipelines from rewiring.
   • --retry-ids: retry pipelines in Failed state.
   • At least one of --add-ids, --remove-ids, --retry-ids, --service-connection-id, or --repository-mapping is required.

   Retry-only shortcut:

   az devops migrations pipelines retry --org $org --repository-id $rid --pipeline-ids 43
   

5. Review and approve at cutover when stage is ReviewForCutover:

   az devops migrations cutover review --org $org --repository-id $rid -o table
   

   Review key fields:

   Field	Meaning
   FailedCount / BlockedCount / PendingCount / TotalUnprocessedCount	Counts of unprocessed items (failed, blocked, pending, and total)
   RequiresPipelineVerification (requiresPipelineVerificationAcknowledgment)	If true, approval must include --pipelines-verified
   State / Type / PullRequestUrl (from failedItems[])	Per-item failure details

6. Approve cutover:

   az devops migrations cutover approve --org $org \
                                       --repository-id $rid \
                                       --pipelines-verified
   

   If you also accept unprocessed items:

   az devops migrations cutover approve --org $org \
                                       --repository-id $rid \
                                       --accept-failures 3 \
                                       --pipelines-verified
   

   You must supply at least one of --accept-failures or --pipelines-verified.

1. In the migration dashboard, open the menu for the migrating repository and select Rewire pipelines.
2. Select Rewire on the pipelines you want to connect.
3. A blue status indicator shows rewired pipelines.