This article describes the process for migrating repositories owned by an organization from github.ncsu.edu to the GitHub Enterprise Cloud service.
The on-prem GitHub service is being retired in favor of new GitHub Enterprise Cloud service. Users are required to migrate their data to the Cloud service by 2025-12-20.
To migrate personally owned repositories, please refer to the user-owned repository migration KB article.
Training Resources
- Migrating to GitHub Enterprise Cloud Town Hall - February 24th @ 2pm - Recording - Slides
- Migrating to GitHub Enterprise Cloud REPORTER Course - March 4th @ 3pm - On-Demand Training
Prerequisites
Before starting a migration, ensure that you know what organization you are migrating to. If you don't have one request an organization for your unit.
Additionally, please review the following material before starting your migration process:
- GitHub Enterprise Cloud Service Policies
- Differences between the github.ncsu.edu and GitHub Enterprise Cloud services
- Logging in to GitHub Enterprise Cloud
Organization Configuration and Team Creation
You may wish to configure your basic organization settings prior to your first repository migration. Unfortunately, there is no automated process to migrate entire organizations between the two services, so any configuration changes will need to be made manually. You will need to create any Teams in GitHub cloud as the migration does not carry those over.
The GitHub Service Team provides some recommendations for basic organization configuration to get started.
If you make use of features such as GitHub Actions, Secrets and Variables, etc, be sure to consult the official GitHub documentation and update your settings appropriately.
Configure SSH Keys
If you use SSH keys to access your repository, you'll need to ensure that your new GitHub Enterprise Cloud account has the key added.
Note that if you already have a personal account on github.com which uses the same key, you'll need to remove it from your personal account, or generate a new key.
See the official GitHub documentation for Adding a New SSH Key to Your GitHub Account.
You'll also need to authorize the SSH key for SSO.
Obtaining Migration Tokens
The migration tool requires two sets of authorization tokens: one from the github.ncsu.edu service and one from the GitHub Enterprise Cloud service.
Keep these tokens safe, as they grant a high level of access into your GitHub organizations. When you are finished with your migrations, you should delete them from GitHub.
Token for github.ncsu.edu
1. While logged into an account with organization owner permissions in github.ncsu.edu, open the Token Settings page: https://github.ncsu.edu/settings/tokens
2. Click Generate in the top-right corner, and select the (classic) token option.
3. Give the token a descriptive name, such as "GitHub Migration Token".
4. Select an appropriate expiration date for the token.
5. Select the following Scopes for the token: repo (ALL), admin:org (ALL)
6. Click Generate Token at the bottom of the page.
7. Copy the token to a safe location. The token will not be shown again, and you'll need it to migrate your repositories.
Token for GitHub Enterprise Cloud
1. While logged into an account with organization owner permissions in GitHub Enterprise Cloud, open the Token Settings page: http://github.com/settings/tokens
2. Click Generate in the top-right corner, and select the (classic) token option.
3. Give the token a descriptive name, such as "GitHub Migration Token".
4. Select an appropriate expiration date for the token.
5. Select the following Scopes for the token: repo (ALL), workflow, admin:org (ALL)
6. Click Generate Token at the bottom of the page.
7. Copy the token to a safe location. The token will not be shown again, and you'll need it to migrate your repositories.
8. Return to the list of tokens and click Configure SSO next to the new token, and click on your organization name.
9. You will be redirected to an EntraID login and back, and the token should show as Authorized.
Setting up the GitHub CLI
To migrate your repositories, you'll need to use the GitHub Command-Line tool.
Instructions for setting up the tool are available here: https://github.com/cli/cli#installation
Downloads are available for Windows, MacOS, RedHat Linux, and Ubuntu Linux.
Configuring the GitHub CLI
Once you have set up the GitHub CLI, you'll need to give it the authorization token and install the `gei` extension.
Run the following command in a command-line terminal as your user account ("export" is used on Linux for setting environmental variables - on Windows use "set"):
export GH_HOST=github.com
gh auth login --git-protocol ssh --with-token
(paste GitHub Enterprise Cloud token)
(press ctrl-D)
gh extension install github/gh-gei
✓ Installed extension github/gh-gei
gh extension upgrade github/gh-gei
[gei]: already up to date
✓ Successfully checked extension upgradesExecuting the Migration
To migrate a repository, you'll use the GitHub CLI you previously configured.
You'll need the following information:
- Access Token for github.ncsu.edu
- Access Token for GitHub Enterprise Cloud
- The name of your organization in github.ncsu.edu
- The name of your organization in GitHub Enterprise Cloud
- The name of the repository you'd like to migrate
Run the following commands to migrate the repository ("export" is used on Linux for setting environmental variables - on Windows use "set"):
export GH_PAT=$(cat)
(Paste GitHub Enterprise Cloud token)
(Press ctrl+D)
export GH_SOURCE_PAT=$(cat)
(Paste github.ncsu.edu token)
(Press ctrl+D)
export GH_HOST=github.com
source_org=$(cat)
(Enter your github.ncsu.edu organization name)
(Press ctrl+D)
target_org=$(cat)
(Enter your GitHub Enterprise Cloud organization name)
(Press ctrl+D)
repository=$(cat)
(Enter your repository name)
(Press ctrl+D)
gh gei migrate-repo \
--github-source-org ${source_org} \
--source-repo ${repository} \
--github-target-org ${target_org} \
--target-repo ${repository} \
--ghes-api-url https://github.ncsu.edu/api/v3
The migration tool will output information about the status of the migration, and will report when it is finished.
Post Migration Actions
Check the Migrated Repository
Once the migration has finished, you should check the migrated repository in GitHub Enterprise Cloud to ensure that everything migrated successfully.
You should see the full git history of the repository in the Code view, and all Issues, Pull Requests, Projects, and Wikis should have migrated.
There is a copy of the migration report added as an Issue on the repository. You may choose to review this as well and close the Issue.
The repository will be set as Private by default, with no access to users other than the one who migrated it. Be sure to set the visibility and assign permissions as appropriate.
Test that you and your team are able to successfully access and clone the repository, and if you have service accounts which need access, test those as well.
Webhooks, GitHub Secrets, and Action Runners
Note that while webhook configurations for repositories will migrate successfully, they will be disabled by default after activation and will need to be reactivated.
If your webhook used a secret as a part of it's configuration, you'll need to manually enter the secret again, as it will not have transferred.
Any GitHub Secrets set on the repository will also need to entered manually, as they are not transferred in the migration.
Any configured self-hosted Action Runners will need to be set up for the migrated repository.
Update User Attributions
When the repository is imported, the authors of each interaction with the repository are mocked into a separate entity called a "Mannequin".
To ensure that issues, comments, pull requests, etc, are attributed to the correct user, you should assign these Mannequins to their correct users.
See the official GitHub documentation for Reclaiming mannequins.
Update References to the Repository and Test Integrations
If you have any local copies of the repository, you'll want to update the origin URL to point to the new repository.
git remote set-url origin <HTTPS/SSH URL>You may need to update references in your IDE, scripts and automation, configuration files, etc.
Ensure that everything is using the new repository correctly, and that all business workflows have been tested.
Remove the github.ncsu.edu Repository
To finalize the migration, you should remove the old repository on github.ncsu.edu. This ensures that no one attempts to read or update the old repository.
1. Navigate to the original repository in your Web Browser.
2. Click on Settings at the right end of the repository menu.
3. Scroll down to the Danger Zone, and click "Delete this repository".
4. Follow the on-screen instructions to finalize the deletion.
Bulk Migration of Repositories
If you have a number of repositories to migrate github.ncsu.edu to GitHub Enterprise Cloud, this script has been written to help automate some steps of the above process: https://github.com/ncstate-oit-csi/migrate_github_repos
Common Issues with Migrating Organization-Owned Repositories to GitHub Enterprise Cloud
Please refer to the following article if you run into issues: Common Issues with Migrating Organization-Owned Repositories to GitHub Enterprise Cloud