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.
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
Training Resources
- Migrating to GitHub Enterprise Cloud Town Hall - February 24th @ 2pm - Recording - Slides
- Migrating to GitHub Enterprise Cloud REPORTER Course - March 4th @ 3pm - Registration Link - On-Demand link coming soon
- GitHub Office Hours - 10am-12pm on March 14th, March 28th, April 11th, April 25th, May 9th, May 23rd - https://go.ncsu.edu/coworking
Prerequisites
Before starting a migration, ensure that your have requested an organization for your unit (email github@help.ncsu.edu to request Organization creation), and that you are able to log in and access the organization.
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 organizations between the two services, so any configuration changes will need to be made manually.
In particular, ensuring that all organization members have been added and assigned to an appropriate Team within the organization will make assigning access controls to migrated repositories easier. Note that the baseline permissions for organization members is enforced to "No Permissions", and so organization members must be granted explicit access to repositories. Teams can help to streamline this process, and makes overall management of permissions easier. Additional tooling for automating team membership will be available in the future.
Some other useful configuration options for your organization may be:
- Setting a descriptive display name
- Uploading an profile picture to visually identify your organization
- Setting your primary ServiceNow queue email as your public email address
- Adjusting Member privileges to determine what actions organization members may perform
- Defining default repository labels
- Enabling/disabling organizational level Projects
- Setting up organization level Action Runners
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.
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 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 upgradesMigrating Repositories
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
Note: When migrating a personally owned repository, use your username in place of the organization name.
Run the following commands to migrate the repository:
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.
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.
Test that you and your team are able to successfully clone the repository, and if you have service accounts which need access, test those as well.
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
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.
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.