Migration Limitations

As mentioned in Migration Process, migrations are primarily facilitated by GitHub Enterprise Importer (GEI), GitHub’s migration product. GEI has limitations, it does not migrate every aspect of a repository from one GitHub enterprise to another. The GEI documentation provides information on data that is migrated with GEI and data that is not migrated.

Of the data types that are not migrated by GEI, we believe the following will be of most concern for VA teams:

1. Users, teams, and their repository access assignments
2. Secrets of any type, which includes Dependabot, Actions, webhooks, etc.
3. Actions resources such as variables, environments, and self-hosted runners
4. GitHub Apps and App installations
5. Git LFS Objects
6. Packages
7. Projects
8. Custom repository properties
9. Repository rulesets
10. Issue types and relationships

The GitHub team plans to extend GEI with custom support to help migrate the following resource types:

1. Projects (partial)
2. Issue types and relationships. The support for relationships may not cover all cases. We will provide more information on our support for relationships as it becomes available.
3. Actions secrets, variables, and environments. Secrets will be names only since we cannot access the secret values.
4. Packages
5. Repository rulesets and custom properties. For rulesets, the bypass settings will not be migrated because those actors (even built-in ones like repository roles) will not directly translate to the destination organization.
6. Git LFS Objects

The initial version of the migration tooling may not contain these extensions since we do not want to delay basic migrations for teams that do not need to wait on support for these items. We will provide more information on these extensions as we get closer to the date of migrations availability. Note that since Projects are an organization level entity that may reference many repositories, there will be a separate workflow for migrating a project and all repositories and issues referenced by the project must be migrated before the project is migrated.

In addition to the data type limitations, there are some notable size limitations with GEI:

1. 2 GB size limit for a single Git commit: No single commit in the repository can exceed 2GB.
2. 400MB file size limit: No single file in your repository can exceed 400MB. Note that the 400MB limit is just a migration limit, the standard GitHub file size limit is 100MB and that will be enforced after migration, preventing the addition of any new files greater than 100MB.
3. 40 GB export size limit: The compressed archives for both Git source and metadata cannot exceed 40GB, each.
4. 10 GB size limit on release artifacts: If a repository has > 10GB of release artifacts then releases may be omitted from the repository migration.

The first two limitations should not pose a problem for VA GHEC migrations since those limitations are already in place for general github.com use. The VA also does not have any repositories nearing 40GB in Git data size. It is more difficult to estimate the potential size of the metadata archive however our analysis leads us to believe that there may be a handful of repositories that may exceed 40GB of metadata size due to the number of GitHub releases and their total artifact size. Otherwise, we expect the vast majority of repositories will not have any size issues.

We have identified 5 VA repositories with more than 10GB of release artifacts. The GitHub team will work with the owners of these repositories to develop a plan and custom support for migrating them.

GHEC Analysis

The GitHub team has analyzed the GHEC repositories for the use of these resources that will not be migrated automatically. We have compiled that information into a spreadsheet to assist VA teams in understanding how these limitations may affect migrations of their repositories. See the GHEC Analysis section for more information and a link to the spreadsheet.