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
Migrating User Owned Repositories
To migrate user owned repositories, it is recommended to use the Importer Tool in the GitHub web interface.
Note that Issues, Pull Requests, Wikis, etc, will NOT be included in the migration. In cases where these are critical to keep, the repository likely holds significance to university business and should be owned by an organization. Therefore it is recommended to transfer the repository to an organization on github.ncsu.edu, and then follow the steps for migrating repositories owned by an organization as documented below.
For more information on using the Importer tool, see the official GitHub documentation here: https://docs.github.com/en/enterprise-cloud@latest/migrations/importing-source-code/using-github-importer/importing-a-repository-with-github-importer
Be sure to use the HTTPS URL for your repository, as the importer tool cannot use the SSH URL.
Additionally, for the password, create a classic Personal Access Token (PAT) for your account with the full "repo" permission enabled, and use the PAT as the password.
After the migration, be sure to follow the Post Migration Actions at the bottom of the article!
Migrating Organization Owned Repositories
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
- Configuring organization level Webhooks and Secrets
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 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 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.
For organization migrated repositories, 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 (Organization Only)
This section only applied to repositories migrated into organizations.
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.