Phase 5. Migrate your repositories from Azure DevOps to Github

Perform a trial run and then migrate your repositories from Azure DevOps to GitHub.

In this article

Prerequisites

  • You must have completed all previous phases of this guide.
  • Ensure you understand the data that will be migrated and the known support limitations of the Importer. For more information, see Phase 1. Understand migrations from Azure DevOps to GitHub.
  • While not required, we recommend halting work during your production migration. The Importer doesn't support delta migrations, so any changes that happen during the migration will not migrate. If you choose not to halt work during your production migration, you'll need to manually migrate these changes.

Generate a migration script

If you want to migrate multiple repositories to GitHub Enterprise Cloud at once, use the GitHub CLI to generate a migration script. The resulting script will contain a list of migration commands, one per repository.

Note

Generating a script outputs a PowerShell script. If you're using Terminal, you will need to output the script with the .ps1 file extension and install PowerShell for either Mac or Linux to run it.

To generate a migration script, run the gh ado2gh generate-script command.

Shell
gh ado2gh generate-script --ado-org SOURCE --github-org DESTINATION --output FILENAME

Replace the placeholders in the command above with the following values.

PlaceholderValue
SOURCEName of the source organization
DESTINATIONName of the destination organization
FILENAMEA filename for the resulting migration script

If you're using Terminal, use a .ps1 file extension as the generated script requires PowerShell to run. You can install PowerShell for Mac or Linux.

Additional arguments

ArgumentDescription
--target-api-url TARGET-API-URLIf you're migrating to GHE.com, add --target-api-url TARGET-API-URL, where TARGET-API-URL is the base API URL for your enterprise's subdomain. For example: https://api.octocorp.ghe.com.
--allAdd additional functionality to the script, such as rewiring pipelines, creating teams, and configuring Azure Boards integrations.
--download-migration-logsDownload the migration log for each migrated repository. For more information about migration logs, see Accessing your migration logs for GitHub Enterprise Importer.

Reviewing the migration script

After you generate the script, review the file and, optionally, edit the script.

  • If there are any repositories you don't want to migrate, delete or comment out the corresponding lines.
  • If you want any repositories to have a different name in the destination organization, update the value for the corresponding --target-repo flag.
  • If you want to change the visibility of a new repository, update the value for the corresponding --target-repo-visibility flag. By default, the script sets the same visibility as the source repository.

Perform a trial run

To help uncover problems that might be unique to your enterprise, we highly recommend performing a trial run of your migration. With a trial run, you'll learn:

  • Whether the migration for a given repository can complete successfully.
  • Whether you can get the migrated repository back to a workable state.
  • How long a migration will take to run.

Trial runs can take place at any time, and work does not need to halt during the migration. To reduce the time it takes to complete your trial migrations, you can schedule the batches for your trial runs back-to-back. Users of those repositories can then validate the results on their own time.

  1. Create a test organization for your trial migrations.

    You can use a single organization for all trial runs, or you can create one test organization for each intended destination organization. Consider including -sandbox at the end of the organization names, to clarify that the organizations are intended only for migration validation and not for production. You can delete the test organizations after you're done.

  2. Run the trial migrations.

  3. Confirm that you are able to complete the follow-up tasks in Phase 6. Follow-up tasks.

  4. Ask users to validate the results of the migrations.

  5. Resolve any issues uncovered by your trial migrations.

  6. Optionally, delete the test organization.

Migrate repositories

If your trial run was successful, and you were able to complete the follow-up tasks, you can proceed to the real migration.

Warning

We recommend halting work in the repositories you are migrating. Any changes made during or after the migration will need to be manually migrated.

To migrate multiple repositories, run the script you generated. Replace FILENAME in the commands below with the filename you provided when generating the script.

  • If you're using Terminal, use ./.

    Shell
    ./FILENAME

  • If you're using PowerShell, use .\.

    Shell
    .\FILENAME

Next steps

In the next and final phase, you'll perform follow-up tasks, check logs, and get your repositories ready to use. See Phase 6. Follow-up tasks.