Edit

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.

Note

Prerequisite setup uses both the Azure DevOps portal and GitHub UI (for one-time tasks such as creating a service connection, registering an agent, and creating a PAT) and the command line (for installing tooling). Each section is labeled so you know where to work.

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, use either method:

  • Azure DevOps CLI (recommended):

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

    The command returns the repository GUID. Save it for use when you start the migration.

  • Azure DevOps portal:

    1. In your Azure DevOps project, go to Project Settings > Repositories.
    2. Select the repository you want to migrate.
    3. In the browser address bar, copy the GUID that appears after repositoryId=. It looks like xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Save it for use when you start the migration.

Access requirements

Azure DevOps Services

  • You must have the Enterprise Live Migrations: Manage Migrations permission set to Allow at the repository level. To check, go to Project Settings > Repositories > Security and confirm your group or user account has this permission. If you don't, contact your Project Collection Administrator (PCA) or Project Administrator (PA) to request access. For more information, see Set Git repository permissions.
  • If no self-hosted Linux agent is available, a PCA or someone with permission to administer the agent queue must create and register one.
  • A user with the appropriate permissions must create the service connection that uses the GitHub PAT.

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 a PAT in GitHub, then store it in an Azure DevOps service connection.

Create a PAT in GitHub (GitHub portal)

  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.

Create the service connection in Azure DevOps (Azure DevOps portal)

  1. Sign in to your Azure DevOps organization.
  2. Go to Project Settings > Pipelines > Service connections.
  3. Select New service connection, choose GitHub Enterprise Server, and then select Next.
  4. For Authentication method, select Personal Access Token.
  5. Enter the GitHub Enterprise URL and paste the GitHub PAT from the previous procedure.
  6. Verify and save the service connection.
  7. Open the service connection and copy the ID. You need this ID when you start the migration.

For more information, see Service connections in Azure Pipelines.

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 is 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 whose 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.

Important

You must use a Linux-based agent. Windows-based and macOS-based agents aren't supported.

Values to collect

Use this checklist to collect the values you need before you start the migration.

Field Example Your value
Azure DevOps organization URL https://dev.azure.com/myorg
Azure DevOps project name MyProject
Azure DevOps repository name my-repo
Azure DevOps repository GUID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Target GitHub organization URL https://contoso.ghe.com/MyOrg
Target repository name MyProject-MyRepo
Service connection ID cd32d354-xxxx-xxxx-xxxx-xxxx
GitHub PAT for the service connection xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Self-hosted Linux agent pool name Default
GitHub user ID MyHandle

Next step

Start the migration

Related content

  • Last updated on