About migrations between GitHub products

About migrations between GitHub products

With GitHub Enterprise Importer, you can migrate data from GitHub Enterprise Server to GitHub Enterprise Cloud, or migrate data from GitHub.com to another account on GitHub Enterprise Cloud.

For example, GitHub Enterprise Importer can help your company to:

• Adopt GitHub Enterprise Cloud with data residency by migrating your enterprise to GHE.com
• Adopt certain features on GitHub.com, such as Enterprise Managed Users or new billing models, by migrating between enterprises on GitHub.com
• Benefit from simplified administration and new features by migrating from GitHub Enterprise Server to GitHub Enterprise Cloud

If your migration source is an account on GitHub.com, you can migrate individual repositories between organizations, or migrate entire organizations between enterprises. If your migration source is GitHub Enterprise Server, you can migrate individual repositories.

The data that GitHub Enterprise Importer migrates depends on the source of the migration and whether you are migrating a repository or organization.

Considerations for migrations to GitHub Enterprise Cloud

Before you use GitHub Enterprise Importer, understand the following considerations:

• If you already use GitHub Enterprise Cloud: A GitHub Enterprise plan entitles you to one deployment of GitHub Enterprise Cloud.

  For example, if you already use GitHub.com, and you also want to migrate from GitHub Enterprise Server to GHE.com, your usage for both won't be covered under a single plan.

• If you're migrating to Enterprise Managed Users: You will need to integrate with an identity provider to manage user accounts. Check the level of support for your identity provider before you start. See About Enterprise Managed Users.

• If you're migrating from GitHub Enterprise Server: Be aware that GitHub applies rate limits to certain actions, which are disabled by default on GitHub Enterprise Server. See Rate limits for the REST API.

• If you're migrating to GitHub Enterprise Cloud with data residency: Be aware that certain features are unavailable, and some features require different or additional configuration. See Feature overview for GitHub Enterprise Cloud with data residency.

Data that is migrated from GitHub Enterprise Server

git clone --mirror OLD-REPOSITORY-URL
cd OLD-REPOSITORY-NAME
git remote add new-origin NEW-REPOSITORY-URL
git push new-origin --mirror

git clone --mirror OLD-REPOSITORY-URL
cd OLD-REPOSITORY-NAME
git remote add new-origin NEW-REPOSITORY-URL
git push new-origin --mirror

To migrate from GitHub Enterprise Server (GHES), you must have GHES version 3.4.1 or higher. The data that is migrated depends on the version you're using.

Different size limits per repository apply depending on your GHES version.

Data that is not migrated

Currently, the following data is not migrated.

• Audit logs
• Code scanning results
• Commit status checks
• Dependabot alerts
• Dependabot secrets
• Discussions at the repository level
• Edit history of issue comments and pull request comments
• Fork relationships between repositories (see About forks)
• GitHub Actions secrets, variables, environments, self-hosted runners, larger runners, or workflow run history
• GitHub Apps and GitHub App installations
• Git LFS objects and large binaries (repositories using Git LFS are still supported, see Limitations of GitHub Enterprise Importer)
• Packages in GitHub Packages
• Projects (classic) at the organization level
• Projects (the new projects experience)
• References between pull requests and issues in different repositories (see Autolinked references and URLs)
• Remediation states of secret scanning results
• Repositories owned by user accounts
• Repository stars
• Repository watchers
• Rulesets
• Tag protection rules
• Users' profiles, SSH keys, signing keys, or personal access tokens
• Webhook secrets
• Teams
• User or team access to the repository
• Repository settings for pull requests

Branch protections

Branch protections apply a specified set of rules to a specific branch name or branch name pattern. For more information, see About protected branches.

Branch protections will always be migrated, but certain rules will not be migrated. The following branch protection rules are not migrated.

• Allow specific actors to bypass required pull requests
• Require approval of the most recent push
• Require deployments to succeed before merging
• Lock branch
• Restrict pushes that create matching branches
• Allow force pushes

The following limitations also apply:

• If a branch protection rule optionally allows you to specify people, teams, or apps that are exempt from the rule, such as "Restrict who can dismiss pull request reviews," the exceptions will not be migrated.
• If the "Allow force pushes" rule is enabled in "Specify who can force push" mode, the rule will not be migrated.

Data that is migrated from GitHub.com

If your migration source is an account on GitHub.com, you can migrate individual repositories between organizations, or migrate entire organizations between enterprises.

Migrated data for an organization

When you migrate an organization, a new organization is created within the destination enterprise account. Then, the following data is migrated to the new organization.

• Teams
• Repositories
• Team access to repositories
• Member privileges
• Organization-level webhooks (must be re-enabled after your migration, see Enabling webhooks)
• Default branch name for new repositories created in the organization

All repositories are migrated with private visibility. If you want to set a repository's visibility to public or internal, you can do this after the migration using the UI or API.

Team membership is not migrated. After the migration, you'll need to add members to migrated teams. For more information, see Overview of a migration between GitHub products.

Migrated data for a repository

When you migrate a repository, either directly or as part of an organization migration, only the following data is migrated.

• Git source (including commit history)
• Pull requests
• Issues
• Milestones
• Wikis (excluding attachments)
• GitHub Actions workflows
• Commit comments
• Active webhooks (must be re-enabled after your migration, see Enabling webhooks)
• Repository topics
• Repository settings
  • Branch protections (see Branch protections for more details)
  • GitHub Pages settings
  • Autolink references
  • GitHub Advanced Security settings
  • Pull request settings
    • Automatically delete head branches
    • Allow auto-merge
    • Allow merge commits (commit message setting is reset to the default message)
    • Allow squash merging (commit message setting is reset to the default message)
    • Allow rebase merging
• Releases (up to 10 GB per repository)
• User history for the above data
• Attachments (see Attaching files)

Data that is not migrated

Currently, the following data is not migrated.

• Codespaces secrets
• Audit logs
• Code scanning results
• Commit status checks
• Dependabot alerts
• Dependabot secrets
• Discussions at the repository level
• Edit history of issue comments and pull request comments
• Fork relationships between repositories (see About forks)
• GitHub Actions secrets, variables, environments, self-hosted runners, larger runners, or workflow run history
• GitHub Apps and GitHub App installations
• Git LFS objects and large binaries (repositories using Git LFS are still supported, see Limitations of GitHub Enterprise Importer)
• Packages in GitHub Packages
• Projects (classic) at the organization level
• Projects (the new projects experience)
• References between pull requests and issues in different repositories (see Autolinked references and URLs)
• Remediation states of secret scanning results
• Repositories owned by user accounts
• Repository stars
• Repository watchers
• Rulesets
• Tag protection rules
• Users' profiles, SSH keys, signing keys, or personal access tokens
• Webhook secrets
• User access to the repository

When you migrate a repository directly, teams and team access to repositories are not migrated.

Branch protections

Branch protections apply a specified set of rules to a specific branch name or branch name pattern. For more information, see About protected branches.

Branch protections will always be migrated, but certain rules will not be migrated. The following branch protection rules are not migrated.

• Allow specific actors to bypass required pull requests
• Require approval of the most recent push
• Require deployments to succeed before merging
• Lock branch
• Restrict pushes that create matching branches
• Allow force pushes

The following limitations also apply:

• If a branch protection rule optionally allows you to specify people, teams, or apps that are exempt from the rule, such as "Restrict who can dismiss pull request reviews," the exceptions will not be migrated.
• If the "Allow force pushes" rule is enabled in "Specify who can force push" mode, the rule will not be migrated.

Limitations on migrated data

There are limits to what GitHub Enterprise Importer can migrate. Some are due to limitations of GitHub, while others are limitations of GitHub Enterprise Importer itself.

Limitations of GitHub

• 2 GB size limit for a single Git commit: No single commit in your Git repository can be larger than 2 GB. If any of your commits are larger than 2 GB, you will need to split the commit into smaller commits that are each 2 GB or smaller.
• 255 byte limit for Git references: No single Git reference, commonly known as a "ref", can have a name larger than 255 bytes. Usually, this means that your references cannot be more than 255 characters long, but any non-ASCII characters, such as emojis, may consume more than one byte. If any of your Git references are too large, we'll return a clear error message.
• 100 MB file size limit: No single file in your Git repository can be larger than 100 MB. Consider using Git LFS for storing large files. For more information, see Managing large files.

Limitations of GitHub Enterprise Importer

• 10 GB size limit for a Git repository: This limit only applies to the source code. To check if the repository archive is over the limit, use the git-sizer tool and review the total blob size in the output. The git-sizer tool also helps to identify potential issues related to large files, blob size, commit size, and tree counts that could impact migrations.
• 10 GB limit for metadata: The Importer cannot migrate repositories with more than 10 GB of metadata. Metadata includes issues, pull requests, releases, and attachments. In most cases, large metadata is caused by binary assets attached to releases. You can exclude releases from the migration with the migrate-repo command's --skip-releases flag, and then move your releases manually after the migration.
• Git LFS objects not migrated: The Importer can migrate repositories that use Git LFS, but the LFS objects themselves will not be migrated. They can be pushed to your migration destination as a follow-up task after the migration is complete. For more information, see Duplicating a repository.
• Follow-up tasks required: When migrating between GitHub products, certain settings are not migrated and must be reconfigured in the new repository. For a list of follow-up tasks you'll need to complete after each migration, see Overview of a migration between GitHub products.
• Delayed code search functionality: Re-indexing the search index can take a few hours after a repository is migrated, and code searches may return unexpected results until re-indexing is complete.
• Rulesets configured for your organization can cause migrations to fail: For example, if you configured a rule that requires email addresses for commit authors to end with @monalisa.cat, and the repository you're migrating contains commits that don't comply with this rule, your migration will fail. For more information about rulesets, see About rulesets.
• Mannequin content might not be searchable: Mannequins are placeholder users to which imported content (such as issues, pull requests, comments, etc.) is associated. When you search for content associated with a mannequin, such as assigned issues, the issues may not be found. Once a mannequin is reclaimed, the content should be found via the new owner. For more information, see Reclaiming mannequins for GitHub Enterprise Importer.

Getting started

Before you migrate between GitHub products, you should plan out how you will run your migration. Before migrating any data, you will need to choose someone to run the migration. You must grant that person the necessary access for both the source and the destination of the migration. We also recommend you run a trial migration first.

For an overview of the migration process from beginning to end, see Overview of a migration between GitHub products.