Übersicht über die Migration zwischen GitHub-Produkten

Overview

With GitHub Enterprise Importer, you can migrate to GitHub Enterprise Cloud. For more information, see About GitHub Enterprise Importer.

If you're migrating between GitHub products, such as from GitHub Enterprise Server to GitHub Enterprise 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 About GitHub Enterprise Importer.

Planning your migration

To plan your migration, ask yourself the following questions.

• 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 GitHub.com, decide whether you want to migrate on an organization-by-organization basis or on a repository-by-repository basis.

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?

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. To gather this data, use the gh-repo-stats extension for the GitHub CLI. This open-source tool generates a report that details how much data there is to migrate for an organization.

• 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.

After you use the analyzer, 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.

1. Use the gh-repo-stats extension for the GitHub CLI, then review your migration inventory.
2. To understand when teams can be ready to migrate, interview stakeholders.
3. Fully review the rest of this guide, then decide on a migration timeline.

Do we understand what will be migrated?

Ensure that you and your stakeholders understand what data can be migrated by GitHub Enterprise Importer.

1. Review the data that's migrated for your migration source. For more information, see About migrations between GitHub products.
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 Managing access for a migration between GitHub products.
3. Confirm that the person has correctly configured personal access tokens to meet all the access requirements. For more information, see Managing access for a migration between GitHub products.

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.

2. If you chose to grant the migrator role, decide which person or team you'll grant the role to.

3. Grant the migrator role to the person or team. For more information, see Managing access for a migration between GitHub products.

   Note

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

4. Confirm that the person has correctly configured personal access tokens to meet all the access requirements. For more information, see Managing access for a migration between GitHub products.

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 GitHub.com, because you can migrate an entire organization with one command. If you're migrating from another source, the GitHub 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 GitHub CLI command, then move the lines for each repository into different scripts as needed.

1. Decide what your new organization structural will be.
2. Decide if you need to break up your migration effort into smaller batches.
3. If so, decide how you want to break up your migrations.

What is our plan for the enterprise and organization names?

If you are migrating between accounts on GitHub.com, 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 GitHub Enterprise share the same namespace; two user/organization accounts cannot have the same name. Enterprise accounts on GitHub Enterprise share the same namespace; two enterprise accounts cannot have the same name.

Running your migrations

After you complete your planning, you can start the actual migrations. To help uncover problems that might be unique to your enterprise during and after the migration, we highly recommend performing trial runs of all migrations. After resolving any issues uncovered by the trial runs, you can run your production migrations.

Trial migrations help you determine several critical pieces of information.

• Whether the migration for a given repository can complete successfully
• Whether you can get the repository back to a state where your users can successfully start working
• How long a migration will take to run, which is useful for planning migration schedules and setting stakeholder expectations

Trial runs do not require much time coordination. GitHub Enterprise Importer never requires downtime for users of a repository being migrated. However, we recommend halting work during production migrations to ensure that new data isn't created during the migration, which would then be missing from the migrated repository. This isn't a concern for trial migrations, so trial runs can take place at any time. 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.

For repository migrations, we recommend creating a test organization to use as a destination 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.

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 GitHub Enterprise Importer. For more information, see Managing access for a migration between GitHub products.
3. Run the trial migrations.
4. Complete the follow-up tasks described below for the trial migrations.
5. Ask users to validate the results of the migrations.
6. Resolve any issues uncovered by your trial migrations.
7. If your destination uses IP allow lists, configure the list to allow access by GitHub Enterprise Importer. For more information, see Managing access for a migration between GitHub products.
8. If you're running a repository migration and you want to migrate settings for GitHub Advanced Security products, enable GitHub Advanced Security products for the destination organization. For more information, see Managing security and analysis settings for your organization.
9. Run your production migrations. For more information, see About GitHub Enterprise Importer or