2. Complete prerequisites

Azure DevOps Services

Before you use ELM, ensure the following requirements are met across Azure DevOps Services and GitHub Enterprise Cloud with data residency.

Source and target repository requirements

• The migration must originate from Azure DevOps Services (dev.azure.com). Azure DevOps Server isn't supported.
• A target GitHub Enterprise Cloud with data residency organization must already exist.
• The target GitHub repository name must not be in use.

To get the Azure DevOps repository GUID, choose one of the following tabs:

az repos show --repository <repo-name> --query id -o tsv

Access requirements

Azure DevOps Services

GitHub Enterprise Cloud with Data Residency

• A GitHub Enterprise admin must create the personal access token (PAT) and be able to create a service connection in Azure DevOps. The admin then shares the service connection ID with the person running the migration.

Authentication setup

Create two PATs in GitHub:

• One PAT for the service connection.
• One personal PAT for the migration operator.

Create the service connection PAT and service connection

1. In GitHub, go to Settings > Developer Settings and select Personal access tokens.

2. As a GitHub Enterprise admin, create a classic PAT with the following permissions:

   • repo (all)
   • workflow
   • read:org
   • read:user
   • admin:enterprise (all)

3. Copy the PAT and store it securely.

4. Select Configure SSO to grant the PAT access to the target organization.

5. Sign in to your Azure DevOps organization.

6. Go to Project Settings > Pipelines > Service connections.

7. Select New service connection, choose GitHub Enterprise Cloud with data residency, and then select Next.

8. For Authentication method, select Personal Access Token.

9. Enter the GitHub Enterprise URL and paste the GitHub PAT from step 3.

10. Verify and save the service connection.

11. Open the service connection and copy the ID. You need this ID when you start the migration.

Create the personal migration PAT in GitHub (GitHub portal)

The person performing the migration creates this PAT and uses it to authenticate to GitHub.

1. In GitHub, go to Settings > Developer Settings and select Personal access tokens.

2. Create a classic PAT with the following scopes:

   • repo (full)
   • workflow
   • admin:org
   • user:email

3. Copy the PAT and store it securely.

Required tooling

The steps in this section use the command line. Install the Azure CLI and the Azure DevOps CLI extension on the machine you use to run migration commands.

1. Install the Azure CLI. For more information, see How to install the Azure CLI.

   For example, open Visual Studio Code and run:

   winget install -e --id Microsoft.AzureCLI
   

2. Install the Azure DevOps CLI extension. For more information, see Get started with Azure DevOps CLI:

   az extension add -n azure-devops
   

   The az devops migrations commands ship as part of the standard azure-devops extension. There's no separate ELM extension to install.

3. Verify the extension loaded:

   az devops migrations --help
   

4. To update an existing installation:

   az extension update -n azure-devops
   

5. (Recommended) Set your Azure DevOps organization as the default so every migrations command targets the right host:

   az devops configure --defaults organization=https://dev.azure.com/<org>
   

   If you skip this step and run commands from a folder where the git remote points to a different organization, the CLI's auto-detection picks that remote instead of your --org value. To force it off for a single command, add --detect false.

Configure a self-hosted Linux agent

Use the Azure DevOps portal to select or create an agent pool, and then run the agent setup scripts on a Linux machine.

1. In Project Settings, go to Agent pools under Pipelines, choose the pool you want to use for the migration, and save the pool name.

2. If you don't have a pool to use, create a self-hosted Linux agent. For more information, see Deploy an Azure Pipelines agent on Linux. The short version:

   1. Confirm that you have permission to register an agent. If you're a PCA, you already have this access.
   2. In your Azure DevOps organization settings, go to Pipelines > Agent pools.
   3. Select the Default pool or your self-hosted pool.
   4. Open the Agents tab and select New agent.
   5. In the Get the agent dialog, select Linux and download the agent.
   6. On your Linux machine, unpack the agent into the directory of your choice and change to that directory.
   7. Run ./config.sh and then ./run.sh.

Turn on auditing

ELM records migration lifecycle events in the Azure DevOps audit log, including start, pause, resume, scheduled cutover, and abandon actions. Admins can view these events under Organization settings > Auditing.

Optional setup for hybrid scenarios

Use this section if you plan to keep using Azure DevOps with GitHub after migration.

Install Azure Boards on GitHub

If you plan to continue using Azure Boards after migration, a GitHub enterprise admin must install the Azure Boards app in your GitHub organization before migration starts. This app enables ELM to create the Boards connection so teams can link GitHub commits and pull requests back to Azure DevOps work items.

To verify installation, go to https://<enterpriseUrl>/organizations/<orgName>/settings/installations and confirm that Azure Boards is listed. If Azure Boards isn't listed, ask a GitHub enterprise admin to install the Azure Boards app in your enterprise app catalog.

Create a service connection for pipeline rewiring

If you plan to use Azure DevOps and GitHub in a hybrid setup and connect your GitHub repository to Azure Pipelines, complete these steps before starting the migration.

1. Confirm that the Azure Pipelines app is installed in your GitHub enterprise at https://<enterpriseUrl>/organizations/<orgName>/settings/installations.
2. If Azure Pipelines isn't listed, ask a GitHub enterprise admin to install the app: https://<enterprise>.ghe.com/apps/external-app/azure-pipelines. Select Configure and ensure that Repository access is set to All Repositories.
3. In Azure DevOps, under Project Settings, select Service connections.
4. Select New service connection and choose GitHub Enterprise Cloud with data residency.
5. Add your GitHub URL and organization name, and then select Authorize.
6. Add a service connection name, and then select Save.
7. Open the service connection you created and copy the ID. You need this ID for pipeline rewiring.

Values to collect for CLI-based migration

Use this checklist if you plan to start and manage migration by using Azure DevOps CLI commands instead of the Azure DevOps UI.

Next step

Related content

• Learn about Enterprise Live Migrations
• Start the migration
• ELM CLI reference