UTK Github: Migration from GitHub Enterprise Server to EMU

Tags Github

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”
    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
  • Command Prompt window showing the gh auth login workflow in the GitHub CLI, where the user selects GitHub Enterprise Server, enters the hostname github.utk.edu, chooses HTTPS for Git operations, confirms credential authentication, and proceeds to log in with a web browser to authenticate the 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
    • GitHub Enterprise Personal access tokens settings page showing Developer settings → Personal access tokens, with the Generate new token button highlighted, where the user creates a token for use as a source or destination token during the GEI migration process.
    • 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
  • GitHub Enterprise Personal access tokens (classic) page showing a newly generated token with the Configure SSO option open, where the user authorizes the token for organization access and confirms required scopes such as repo, workflow, and admin:org for migration use.
  • 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
    • Azure Portal Storage account → Access keys page showing Key1 with the Connection string field visible, where the user clicks the copy icon to copy the connection string for use as an environment variable during migration.
  • 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.
Print Article