| title | shortTitle | intro | versions | redirect_from | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Overview of a migration from Azure DevOps to GitHub Enterprise Cloud |
Overview of a migration |
Learn how to complete the entire process of migrating from Azure DevOps to {% data variables.product.prodname_dotcom %} with {% data variables.product.prodname_importer_proper_name %}, from planning to implementation to completing follow-up tasks. |
|
|
With {% data variables.product.prodname_importer_proper_name %}, you can migrate to {% data variables.product.prodname_ghe_cloud %} on a repository-by-repository basis. For more information, see AUTOTITLE.
If you're migrating from Azure DevOps (ADO), you can use this guide to plan and implement your migration and complete follow-up tasks.
Enterprises who migrate from ADO to {% data variables.product.prodname_dotcom %} typically follow a multi-phase approach.
- Migrate repositories from ADO to {% data variables.product.prodname_dotcom %}.
- Migrate pipelines from Azure Pipelines to {% data variables.product.prodname_actions %}.
- Migrate remaining assets, such as boards and artifacts, from ADO to {% data variables.product.prodname_dotcom %}.
This guide will guide you through completing the first phase, migrating repositories to {% data variables.product.prodname_dotcom %}, and assumes you're using the {% data variables.product.prodname_ado2gh_cli %}.
{% data reusables.enterprise-migration-tool.planning-intro %}
- How soon do we need to complete the migration?
- Do we understand what will be migrated?
- Who will run the migration?
- What organizational structure do we want in {% data variables.product.prodname_dotcom %}?
Determine your timeline, which will largely dictate your approach. The first step for determining your timeline is to get an inventory of what you need to migrate.
- Number of repositories
- Number of pull requests
Migrating from Azure DevOps, we recommend the inventory-report command in the {% data variables.product.prodname_ado2gh_cli %}. The inventory-report command will connect with the Azure DevOps API, then build a simple CSV with some of the fields suggested above. To install the {% data variables.product.prodname_ado2gh_cli %} and authenticate, follow steps 1 to 3 in AUTOTITLE.
Migration timing is largely based on the number of pull requests in a repository. If you want to migrate 1,000 repositories, and each repository has 100 pull requests on average, and only 50 users have contributed to the repositories, your migration will likely be very quick. If you want to migrate only 100 repositories, but the repositories each have 75,000 pull requests on average, and 5,000 users, the migration will take much longer and require much more planning and testing.
After you take inventory of the repositories you need to migrate, you can weigh your inventory data against your desired timeline. If your organization can withstand a higher degree of change, then you might be able to migrate all your repositories at once, completing your migration efforts in a few days. However, you may have various teams that are not able to migrate at the same time. In this case, you might want to batch and stagger your migrations to fit the teams' timelines, extending your migration effort.
- Determine how many repositories and pull requests you need to migrate.
- To understand when teams can be ready to migrate, interview stakeholders.
- Fully review the rest of this guide, then decide on a migration timeline.
Ensure that you and your stakeholders understand what data can be migrated by {% data variables.product.prodname_importer_proper_name %}.
For migrations from ADO, {% data variables.product.prodname_importer_proper_name %} only migrates Git repositories, including pull requests and some branch policies. Any other assets, such as pipelines, work items, artifacts, test plans, releases, and dashboards, will remain in ADO.
Because permissions work differently in {% data variables.product.prodname_dotcom %} than in ADO, {% data variables.product.prodname_importer_proper_name %} does not attempt to migrate repository permissions from ADO. For more information, see Configuring permissions.
Service hooks are not migrated from ADO, so you will need to recreate them separately.
- Review the data that's migrated from Azure DevOps. For more information, see AUTOTITLE.
- Make a list of any data that you'll need to manually migrate or recreate.
To migrate a repository, you must be an organization owner for the destination organization, or an organization owner must grant you the migrator role.
- Decide whether you want an organization owner of the destination organization to perform your migrations, or whether you need to grant the migrator role to someone else. {% data reusables.enterprise-migration-tool.grant-migrator-tasks %} For more information, see AUTOTITLE. {% data reusables.enterprise-migration-tool.confirm-migrator-has-correct-pats %} For more information, see AUTOTITLE.
Next, plan the organizational structure you'll create in {% data variables.product.github %}. ADO and {% data variables.product.github %} have different ways of organizing an enterprise's work.
- ADO: Organization > team project > repositories
- {% data variables.product.github %}: Enterprise > organization > repositories
Note
The concept of a team project, which is used to group repositories in ADO, does not exist in {% data variables.product.github %}. We do not recommend treating organizations in {% data variables.product.github %} as the equivalent of team projects in ADO.
After migrating to {% data variables.product.github %}, you should have only one enterprise account and a small number of organizations owned by that enterprise. Each organization from ADO should correspond to a single organization on {% data variables.product.github %}. We do not recommend creating an organization on {% data variables.product.github %} for each team project on ADO.
This may result in a large list of ungrouped repositories within each organization. However, you can manage access to groups of repositories by creating teams. For more information, see AUTOTITLE.
If you want to break your migration effort into batches, the new structure can help you determine your batches. If you have more than one organization in ADO, and each organization's repositories are reasonably sized batches, consider batching by organization. You can use the {% data variables.product.prodname_cli %} to generate a migration script for an entire organization on ADO.
{% data reusables.enterprise-migration-tool.organization-structure-tasks %}
{% data reusables.enterprise-migration-tool.running-your-migrations %}
We recommend creating a test organization to use as a destination for your trial migrations. {% data reusables.enterprise-migration-tool.about-test-organizations %}
- Create a test organization for your trial migrations. {% data reusables.enterprise-migration-tool.trial-migrations-tasks %} {% data reusables.enterprise-migration-tool.configure-destination-ip-allow-list %} For more information, see AUTOTITLE.
- Run your production migrations. For more information, see AUTOTITLE. {% data reusables.enterprise-migration-tool.delete-test-organization %}
{% data reusables.enterprise-migration-tool.follow-up-tasks-intro %}
- Checking the migration status
- Reviewing the migration log
- Setting repository visibility
- Configuring permissions
- Reclaiming mannequins
- Configuring IP allow lists
{% data reusables.enterprise-migration-tool.checking-the-migration-status %}
{% data reusables.enterprise-migration-tool.reviewing-the-migration-log %}
{% data reusables.enterprise-migration-tool.setting-repository-visibility %}
Because permissions work differently in {% data variables.product.prodname_dotcom %} than in ADO, {% data variables.product.prodname_importer_proper_name %} does not attempt to migrate repository permissions from ADO.
If you used the ADO2GH CLI, {% data variables.product.prodname_importer_proper_name %} will create two teams in {% data variables.product.prodname_dotcom %} for each team project in ADO. Each team is granted a different level of access to all repositories that originated from the team project.
| Team | Access to migrated repositories |
|---|---|
| TEAM-PROJECT-Maintainers | Maintainer |
| TEAM-PROJECT-Admins | Admin |
To give access to migrated repositories, you can add people to these teams. You can do this manually on {% data variables.product.prodname_dotcom %}, or if you chose to link the teams to Azure Active Directory (AAD) groups during your migration, by managing group membership in AAD. For more information about manually managing team membership, see AUTOTITLE.
If you aren't using the ADO2GH CLI, or if you require a permissions configuration that is more advanced than this default, configure permissions for your migrated repositories. You can modify the migration script to suit your needs, or you can manually configure permissions after your migration. For more information about managing access to repositories on {% data variables.product.prodname_dotcom %}, see AUTOTITLE.
- Decide what permissions structure you require in {% data variables.product.prodname_dotcom %}.
- If different than the default, make a plan for setting up team membership and permissions.
{% data reusables.enterprise-migration-tool.reclaiming-mannequins %}
If you added the IP ranges for {% data variables.product.prodname_importer_proper_name %} to the IP allow list for your destination organization, you can remove those entries. {% data reusables.enterprise-migration-tool.reenable-idp-ip-restrictions %}
For more information, see AUTOTITLE.