content/migrations/using-github-enterprise-importer/migrating-between-github-products/overview-of-a-migration-between-github-products.md

metadata

title: Overview of a migration between GitHub products
shortTitle: Overview of a migration
intro: >-
  Learn how to complete the entire process of migrating from one {% data
  variables.product.company_short %} product to another with {% data
  variables.product.prodname_importer_proper_name %}, from planning to
  implementation to completing follow-up tasks.
versions:
  fpt: '*'
  ghes: '*'
  ghec: '*'
redirect_from:
  - >-
    /early-access/github/migrating-with-github-enterprise-importer/understanding-github-enterprise-importer/migrating-between-github-products-with-github-enterprise-importer
  - >-
    /early-access/enterprise-importer/understanding-github-enterprise-importer/migrating-between-github-products-with-github-enterprise-importer
  - >-
    /migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/migrating-between-github-products-with-github-enterprise-importer

Overview

With {% data variables.product.prodname_importer_proper_name %}, you can migrate to {% data variables.product.prodname_ghe_cloud %}. For more information, see AUTOTITLE.

If you're migrating between {% data variables.product.company_short %} products, such as from {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_ghe_cloud %}, you can use this guide to plan and implement your migration and complete follow-up tasks. For a full list of supported migration paths, see AUTOTITLE.

Planning your migration

{% data reusables.enterprise-migration-tool.planning-intro %}

• Do we want to migrate by organization or by repository?
• How soon do we need to complete the migration?
• Do we understand what will be migrated?
• Who will run the migration?
• Do we want to maintain a similar organization structure after migrating?

Do we want to migrate by organization or by repository?

First, if your migration source is {% data variables.product.prodname_dotcom_the_website %}, decide whether you want to migrate on an organization-by-organization basis or on a repository-by-repository basis.

If you're migrating from {% data variables.product.prodname_ghe_server %}, you can only migrate repositories.

If you choose repository-by-repository migrations, only repository-level data is migrated. If you pick the organization-by-organization migration strategy, selected organization-level data is also migrated, including teams and their access to repositories.

However, when you migrate an organization, all repositories owned by the source organization are migrated at the same time. You cannot break the repositories into batches or skip migrating any of the organization's repositories. If you have a large number of repositories, or if you can't tolerate downtime for all your repositories at the same time, you might need to run repository migrations instead.

Additionally, an organization migration creates a new organization in the destination enterprise account. If you want to migrate repositories into an existing organization, you'll need to run repository migrations instead.

Finally, you must be an enterprise owner of the destination enterprise account to migrate organizations. If you want to task someone who is not an enterprise owner perform your migrations, they will need to run repository migrations.

How soon do we need to complete the migration?

{% data reusables.enterprise-migration-tool.timeline-intro %}

• Number of repositories
• Number of pull requests
• Number of issues
• Number of users
• Usage of projects and wikis

Migration timing is largely based on the number of pull requests and issues in a repository. If you want to migrate 1,000 repositories, and each repository has 100 pull requests and issues 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 and issues on average, and 5,000 users, the migration will take longer and require much more planning and testing.

{% data reusables.enterprise-migration-tool.timeline-tasks %}

Do we understand what will be migrated?

Ensure that you and your stakeholders understand what data can be migrated by {% data variables.product.prodname_importer_proper_name %}.

1. Review the data that's migrated for your migration source. For more information, see AUTOTITLE.
2. Make a list of any data that you'll need to manually migrate or recreate.

Who will run the migration?

Decide who will run your migrations, and ensure that this person has the required access. Your options will depend on whether you're migrating by organization or by repository.

Deciding who will run organization migrations

To migrate an organization, you must be an organization owner for the source organization, or an organization owner must grant you the migrator role for that organization.

Additionally, you must be an enterprise owner on the destination enterprise account. You cannot grant the migrator role for enterprise accounts.

1. Confirm that the person who will run your migrations is an enterprise owner of the destination enterprise account.
2. If that person is not an organization owner for the source organization, grant them the migrator role for the organization. For more information, see AUTOTITLE. {% data reusables.enterprise-migration-tool.confirm-migrator-has-correct-pats %} For more information, see AUTOTITLE.

Deciding who will run repository migrations

To migrate a repository, you must be an organization owner for both the source organization and the destination organization, or an organization owner must grant you the migrator role for each organization where you're not an owner.

1. Decide whether you want an organization owner 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.

   Remember to grant the migrator role for both the source organization and the destination organization.

{% data reusables.enterprise-migration-tool.confirm-migrator-has-correct-pats %} For more information, see AUTOTITLE.

Do we want to maintain a similar organization structure after migrating?

Next, consider whether you want to maintain a similar organizational structural after migrating. If you want to break your migration effort into batches, this will help you determine your batches. If you intend to keep a one-to-one correspondence between organizations in your source and destination, then we recommend batching migrations by organization. This is the simplest approach, especially if you're migrating from {% data variables.product.prodname_dotcom_the_website %}, because you can migrate an entire organization with one command. If you're migrating from another source, the {% data variables.product.prodname_cli %} can generate a script to migrate all repositories in a single organization.

If you intend to change your organizational structure, consider other batching factors. You can batch repositories owned by similar teams or a business division, or you can batch by the destination organization. We recommend batching by teams if possible. If you batch by business division or destination organizations, you'll increase the number of stakeholders involved, which can lead to shorter windows of time for your migrations.

Even if you change your organizational structure, you can still prepare a script for your migration. Use the {% data variables.product.prodname_cli %} command, then move the lines for each repository into different scripts as needed.

You can run multiple batches simultaneously. For example, if you're batching by teams, you could run the migrations for multiple teams in the same time window.

{% data reusables.enterprise-migration-tool.organization-structure-tasks %}

What is our plan for the enterprise and organization names?

If you are migrating between accounts on {% data variables.product.prodname_dotcom_the_website %}, keep in mind that there are naming constraints for user, organization, and enterprise accounts. If you need to re-use an organization or enterprise name for the migration, we recommend renaming accounts before as opposed to deleting them. Renaming makes a user, organization or enterprise account name available immediately for re-use.

Organization accounts on {% data variables.product.prodname_enterprise %} share the same namespace; two user/organization accounts cannot have the same name. Enterprise accounts on {% data variables.product.prodname_enterprise %} share the same namespace; two enterprise accounts cannot have the same name.

Running your migrations

{% data reusables.enterprise-migration-tool.running-your-migrations %}

For repository migrations, we recommend creating a test organization to use as a destination for your trial migrations. {% data reusables.enterprise-migration-tool.about-test-organizations %}

1. If you're running a repository migration, create a test organization for your trial migrations.
2. If your source organization uses IP allow lists, configure the list to allow access by {% data variables.product.prodname_importer_proper_name %}. For more information, see AUTOTITLE. {% data reusables.enterprise-migration-tool.trial-migrations-tasks %} {% data reusables.enterprise-migration-tool.configure-destination-ip-allow-list %} For more information, see AUTOTITLE.
3. If you're running a repository migration and you want to migrate settings for {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %} products{% endif %}, enable {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %} products{% endif %} for the destination organization. For more information, see AUTOTITLE.
4. Run your production migrations. For more information, see AUTOTITLE or AUTOTITLE. {% data reusables.enterprise-migration-tool.delete-test-organization %}

Completing follow-up tasks

{% data reusables.enterprise-migration-tool.follow-up-tasks-intro %}

• Checking the migration status
• Reviewing the migration log
• Migrating {% data variables.large_files.product_name_short %} objects
• Setting repository visibility
• Configuring {% data variables.product.prodname_actions %}
• Configuring IP allow lists
• Managing {% data variables.product.prodname_GHAS %} features
• Enabling webhooks
• Reinstalling {% data variables.product.prodname_github_apps %}
• Recreating teams
• Reclaiming mannequins

Checking the migration status

{% data reusables.enterprise-migration-tool.checking-the-migration-status %}

Reviewing the migration log

{% data reusables.enterprise-migration-tool.reviewing-the-migration-log %}

Migrating {% data variables.large_files.product_name_short %} objects

{% data variables.product.prodname_importer_proper_name %} does not migrate {% data variables.large_files.product_name_short %} objects. If the source repository uses {% data variables.large_files.product_name_short %}, you can manually push {% data variables.large_files.product_name_short %} objects to the migrated repository locally. For more information, see AUTOTITLE.

Setting repository visibility

{% data reusables.enterprise-migration-tool.setting-repository-visibility %}

Configuring {% data variables.product.prodname_actions %}

If you use {% data variables.product.prodname_actions %} in a repository, your workflows are automatically migrated as part of the Git repository.

During the migration process, {% data variables.product.prodname_actions %} is disabled for all migrated repositories to avoid workflows being accidentally triggered, but {% data variables.product.prodname_actions %} is re-enabled when the migration finishes.

If you were using {% data variables.actions.hosted_runner %}s, self-hosted runners, or encrypted secrets, you must reconfigure them.

Workflow run history for {% data variables.product.prodname_actions %} is not included in migrations.

1. If you use self-hosted runners, reconfigure your runners.

   • Add runners to the appropriate repository, organization, or enterprise. For more information, see AUTOTITLE.
   • To use runners at the organization or enterprise level, update your workflows. For more information, see AUTOTITLE.

2. If you use {% data variables.actions.hosted_runner %}s, reconfigure your runners.

   • Configure runner groups to control access to your runners. For more information, see [AUTOTITLE]({% ifversion ghes %}/enterprise-cloud@latest{% endif %}/actions/using-github-hosted-runners/controlling-access-to-larger-runners).
   • Set up your {% data variables.actions.hosted_runner %}s. For more information, see [AUTOTITLE]({% ifversion ghes %}/enterprise-cloud@latest{% endif %}/actions/using-github-hosted-runners/managing-larger-runners).
   • Update your workflows to point to your runners. For more information, see [AUTOTITLE]({% ifversion ghes %}/enterprise-cloud@latest{% endif %}/actions/using-github-hosted-runners/running-jobs-on-larger-runners).

3. Re-add any encrypted secrets.

   • To use the browser, see AUTOTITLE.
   • To use {% data variables.product.prodname_cli %}, see gh secret in the {% data variables.product.prodname_cli %} documentation.

4. Reconfigure environments. For more information, see AUTOTITLE.

Configuring IP allow lists

If you added the IP ranges for {% data variables.product.prodname_importer_proper_name %} to the IP allow lists for your source or destination organizations, you can remove those entries. {% data reusables.enterprise-migration-tool.reenable-idp-ip-restrictions %}

For more information, see AUTOTITLE.

Managing {% data variables.product.prodname_GHAS %} features

If you enabled {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %} products{% endif %} for the destination organization before migrating repositories, the settings for individual features were migrated. If not, you'll need to re-enable individual features after the migration. For more information, see AUTOTITLE.

There are additional post-migration steps for each feature.

{% data variables.product.prodname_secret_scanning_caps %}

When secret scanning is enabled for the destination repository, a scan of the entire repository will be performed. After the scan is complete, all alerts will be populated, but without remediation states.

You can use the REST API to update the alerts to mirror any remediations in the source repository. For more information, see AUTOTITLE.

The user associated with these updated remediations will be the user who owns the {% data variables.product.pat_generic %} that was used for the API calls, not the user who remediated the alert in the source repository, and the date associated with the remediation will be the date of the API call, not the date the alert was remediated in the source repository.

{% data variables.product.prodname_code_scanning_caps %}

{% data variables.product.prodname_code_scanning_caps %} alerts are not migrated by {% data variables.product.prodname_importer_proper_name %}. However, the alerts are available as SARIF data in the source repository. You can use the REST API to upload this data to the destination repository. For more information, see AUTOTITLE.

{% data variables.product.prodname_code_scanning_caps %} alerts that are populated this way will differ from the original alerts in the source repository.

• Alerts will only include the detection and the latest state of the alert, not the entire timeline from the source repository.
• Alerts will only be identified as open or fixed. Other remediation states, such as dismissed and reopened, will be lost.
• The dates for all events on the alert will be the date of the API call, not the dates when the events originally occurred on the source repository.
• All actors, such as the alert creator, will change to the owner of the {% data variables.product.pat_generic %} used for the API call.

{% data variables.product.prodname_dependabot_alerts %}

When {% data variables.product.prodname_dependabot_alerts %} and the dependency graph are enabled, {% data variables.product.prodname_dependabot_alerts %} will be rebuilt from the current state of the default branch. Remediation states of these alerts are not migrated, and any previous alerts are also not migrated.

You'll need to re-add any encrypted secrets for {% data variables.product.prodname_dependabot %}. For more information, see AUTOTITLE.

Reconfiguring features for {% data variables.enterprise.data_residency_short %}

If you have migrated from {% data variables.product.prodname_dotcom_the_website %} to {% data variables.enterprise.data_residency %}, some features work differently, and some features will require different or additional configuration. See AUTOTITLE.

Enabling webhooks

All active webhooks in the source repository are migrated. However, the migrated webhooks will be disabled by default. You can re-enable these webhooks in the repository settings.

1. Navigate to the settings for the migrated repository.
2. In the "Code and automation" section of the sidebar, click Webhooks.
3. To the right of the webhook you want to enable, click Edit.
4. If you were using a secret token to secure the webhook, under "Secret", re-add the secret.
5. At the bottom of the page, select Active.
6. Click Update webhook.

Reinstalling {% data variables.product.prodname_github_apps %}

If you had any {% data variables.product.prodname_github_apps %} installed on the source repository, you'll need to reinstall them on the migrated repository. For more information, see AUTOTITLE.

Recreating teams

If you migrated on an organization-by-organization basis, you only need to reinstate team membership. If you migrated on a repository-by-repository basis, you will need to recreate teams, give those teams access to repositories, and then reinstate team membership.

Recreating teams for organization migrations

Teams and their repository access are migrated as part of an organization migration, but team membership is not. After your migration, you must add users to the migrated teams.

We highly recommend using team synchronization to manage team membership through your identity provider (IdP). For more information, see AUTOTITLE or, for enterprises that do not use {% data variables.product.prodname_emus %}, AUTOTITLE.

Otherwise, you can manually add members to your organization, and then add organization members to teams. For more information, see AUTOTITLE.

Recreating teams for repository migrations

Teams are not migrated as part of a repository migration. You must manually recreate teams and give each team access to the repository.

1. Re-create teams. For more information, see AUTOTITLE.
2. Add organization members to teams. For more information, see AUTOTITLE.
3. Give each team access to the repository. For more information, see AUTOTITLE.

Reclaiming mannequins

{% data reusables.enterprise-migration-tool.reclaiming-mannequins %}