UTK Github: Migration from GitHub Enterprise Server to EMU

Overview

Documentation on the migration process for moving GitHub resources from GitHub Enterprise Server to GitHub Enterprise Managed Users.

Instructions

Step 1: Install the GEI extension of the GitHub CLI

• Install WinGet with “winget install --id GitHub.cli” inside CMD
  • The file path will most likely be “C:\Program Files\GitHub CLI”
• Install the GEI extension with “gh extension install github/gh-gei”
  
• Run “gh auth login” and login with your github.utk.edu account
  • Select GitHub Enterprise Server
  • GHE hostname: github.utk.edu
  • Select HTTPS or your preferred protocol for Git operations
  • Select Yes to authenticate Git with your credentials
  • Login with a web browser to authenticate GitHub CLI
• 

Step 2: Update the GEI extension of the GitHub CLI

• Open PowerShell and navigate to the same file path where GitHub CLI is installed
• Update the GEI extension with “.\gh extension upgrade github/gh-gei”

Step 3: Set environment variables

• Create personal access tokens for both source and destination organizations
• For the source token, log in to https://github.utk.edu
  • In the top right, click on your profile
  • Go to Settings -> Developer Settings -> Personal access tokens, then click Generate new token
  • 
  • Scope the token to repo and admin:org
  • Once generated, copy the token string “ghp_......”
• For the destination token, go to your EMU instance
  • Go to Settings -> Developer Settings -> Personal access tokens -> Tokens (classic) -> Generate a new token (classic)
  • Scope the token to repo, workflow, and admin:org
  • Then Generate token
• Once generated, Configure SSO to authorize destination (EMU) token
• 
• Set the environment variables for the tokens using these commands in PowerShell:
  • $env:GH_PAT="TOKEN"
  • $env:GH_SOURCE_PAT="TOKEN"

Step 4: Set up a blob storage

• Log in to portal.azure.com
• Access your Azure subscription and resource group
• Create a storage account with the default settings, as it is really just used for temporary storage during the migration
• Once the storage account has been created, navigate to it in your resources and click on the Access Keys tab
  • Copy the Key1 Connection String as this will be used in an environment variable
  • 
• Navigate back to PowerShell and input in the environment variable:
  • $env:AZURE_STORAGE_CONNECTION_STRING=”Connection String”

Step 5: Generate a migration script

For a single repo migration, input the following command and replace each field with the required names of source/destination orgs, etc:

.\gh gei migrate-repo --github-source-org "SOURCE" --source-repo "CURRENT-NAME" --github-target-org "DESTINATION" --target-repo "NEW-NAME" --ghes-api-url "https://github.utk.edu/api/v3" --azure-storage-connection-string $env:AZURE_STORAGE_CONNECTION_STRING --target-repo-visibility “{internal or private}”

• NOTE: This will begin the migration, so make sure everything is edited correctly
• A queue message and then a progress message will display. The migration will take a minimum of ~4 minutes to complete.
• Once the migration is complete, you may skip the remaining steps.

For multiple repos, input the following command:

.\gh gei generate-script --github-source-org “SOURCE” --github-target-org “DESTINATION” --output “FILENAME”.ps1 --ghes-api-url "https://github.utk.edu/api/v3"

• If you want the script to download the migration log for each migrated repository, add the “--download-migration-logs” flag.
• If there are any repositories you don't want to migrate, delete or comment out the corresponding lines.
• If you want any repositories to have a different name in the destination organization, update the value for the corresponding “--target-repo” flag.

Step 6: Migrate repositories

• For a single repo, the above command should have already run and migrated the repo to the destination org.
• For multiple repos, check to make sure the PowerShell script is downloaded to “C:\Program Files\GitHub CLI” and edit any changes to the script (in Notepad)
  • To run the script in PowerShell, type “.\FILENAME”
  • Ex.(“PS C:\Program Files\GitHub CLI> .\FILENAME”)
  • Queue messages and Progress messages will pop up.  This will take a minimum of ~4 minutes to complete.