Quickstart
Last updated
Was this helpful?
Last updated
Was this helpful?
This Quickstart will guide you through the process of migrating repositories from Azure DevOps to GitHub using Warp. You’ll create a new project, set up your Vault, connect your Azure DevOps and GitHub organizations to Warp, and migrate a repository from Azure DevOps to GitHub.
In this Quickstart, you will:
Install the prerequisites
Create a new project to migrate repositories from Azure DevOps to GitHub
Get personal access tokens for Azure DevOps and GitHub
Set up a vault to securely store the personal access tokens and a vault key to unlock them
Connect Azure DevOps to Warp
Migrate a repository from Azure DevOps to GitHub
Search for the 🛠️ emoji if you’d like to skim through this Quickstart’s content while focusing on the steps you need to follow to perform a migration.
Before you can start migrating repositories from Azure DevOps to GitHub, you need to install the following prerequisites:
GitHub CLI (command-line interface) application. Even if you have the GitHub desktop application installed, you’ll need the GitHub CLI to use the Warp command-line extension.
Warp command-line extension. This is a GitHub CLI extension that you’ll use to set up the vault, the secure file that stores the access tokens for your GitHub account and the ADO organization you want to migrate repositories from.
If you already have these prerequisites installed, you can skip this section and move on to section 2, Create a New Project.
If you don’t have these prerequisites installed, you’ll need to install them before you can proceed with the migration. Follow the steps below to install the prerequisites.
First, see if the GitHub CLI is installed on your computer.
🛠️ Open your terminal application (on Windows, it’s Windows PowerShell or Command Prompt; on macOS and Linux, the default terminal is named Terminal).
🛠️ Enter the following command:
If the GitHub CLI is installed, you’ll see a message showing its version number and the URL for its release notes. Here’s an example:
If you see an error message instead, you’ll need to install the GitHub CLI. Go to the GitHub CLI page and follow the instructions there.
🛠️ Once you’ve confirmed that the GitHub CLI is installed on your computer, enter the following command to install the Warp command-line extension:
🛠️ Confirm that the Warp command-line extension is installed by running the following command in a terminal window:
You should see this response:
🙌 If you’ve made it this far, you’ve successfully installed the prerequisites using Warp.
The next step is to create a Project, which in Warp is an object for managing the migration of repositories to GitHub. Typically, you’ll create a new project for a specific migration engagement, such as moving a collection of repositories for your own organization or for a client.
You’ll use the Warp web application to create the project.
🛠️ Open a browser tab or window to the Warp web application at warp.packfiles.io.
🛠️ Click the Sign in with GitHub button and sign in to Warp using your GitHub account.
You will be taken to the Projects page, which lists the current migration projects. At the bottom of the list of projects, you’ll see the Create a New Project link.
🛠️ Click the Create a New Project link.
A new section will appear below the link. This section provides instructions for what to do next, which is to install the Warp GitHub app into the GitHub organization where you will migrate your repositories:
🛠️ Click the Install Warp from the GitHub Marketplace link.
You will arrive at the page for the Warp GitHub app:
🛠️ Click the Configure button to install Warp.
You will be shown a list of user and organization accounts where you can install Warp: You will be shown a list of user and organization accounts where you can install Warp:
🛠️ Select the organization account where Warp will be installed. This should be the organization where you’ll migrate the repositories to. In this example, the organization is Hypotheticorp5678. 🛠️ Select the organization account where Warp will be installed. This should be the organization where you’ll migrate the repositories to. In this example, the organization is Hypotheticorp5678.
After you select the organization, you will go to a page showing which repositories the Warp GitHub app will have access to (all of them) and what it will have read, write, and admin access to.
🛠️ Click the Install button.
You should automatically return to the Projects page in the Warp web application:
🛠️ Click your browser’s Reload button.
You should arrive at the Welcome to Warp page:
🛠️ Click the Next button.
This will take to you the Configure Your Project page. You can do two things on this page:
You can set the name of your project, or choose to keep the default name.
You can invite people on your team to become members of the project. This will take to you the Configure Your Project page. You can do two things on this page:
You can set the name of your project, or choose to keep the default name.
You can invite people on your team to become members of the project.
🛠️ For this quickstart, simply click the Next button.
ℹ️ As the creator of the project, you don’t have to add yourself to the team. You are already a member of the project with Admin access.
The next page to appear is the Connect Your Sources page. You’ll use it in the process of connecting your Azure DevOps and GitHub accounts to Warp.
When you created the project, Warp created a repository named Migration HQ for the GitHub organization that you selected earlier. This repository will be the user interface for managing your migrations.
Your next task is to clone the repository to your local computer. You will then create a file containing your authorizations to access both your Azure DevOps organization and GitHub account, which Warp will use to migrate your repositories. Warp will then add that file to the local repository and push it to Migration HQ.
🛠️ Let’s visit Migration HQ. Click the Migration HQ button.
You will be taken to the Migration HQ page:
🛠️ Clone the Migration HQ repository to your local computer.
In order to migrate repositories from Azure DevOps to GitHub, you need to provide Warp with authorizations to access:
The Azure DevOps organization that contains the repositories you want to migrate, and
Your GitHub account.
You do this by generating Personal Access Tokens (PATs) for both of the above. Warp will use the authorization that these tokens provide to access the repositories in the Azure DevOps organization and migrate them to the destination GitHub organization.
First, let’s generate a PAT for the Azure DevOps organization whose repositories will be migrated.
🛠️ Sign in to Azure DevOps and navigate to the Organizations page. On that page, select the organization whose repositories you want to migrate to GitHub.
You will arrive at the page for the organization you selected. You will arrive at the page for the organization you selected.
Later in this process, you’ll be asked to provide the slug for the Azure DevOps organization you want to connect to Warp. The slug is the part of the URL for the Azure DevOps organization that uniquely identifies the organization. For example:
In the example above, the URL for the Azure DevOps organization’s page is dev.azure.com/joey-ado-testing, which means the slug is joey-ado-testing.
🛠️ Copy the slug for the Azure DevOps organization for later use.
🛠️ Click on the User Settings icon (it looks like a person with a gear) near the top right corner of the page. Select Personal access tokens from the menu that appears.
You will see the Personal Access Tokens page:
🛠️ Click any of the New Token buttons on the page.
A panel will appear, prompting you to create a new personal access token:
🛠️ In the Name field, enter a name for the token. To make it easier to identify, we suggest you include “Warp” in the name.
🛠️ Under Scopes, change the option to Full access.
ℹ️ For the purposes of this Quickstart, we’ll leave the Expiration field at the default value of 30 days.
🛠️ Click the Create button.
You should now see the Success! panel, which will display the personal access token you just created:
🛠️ Copy the token and save it in a safe place — preferably a password manager. Warp needs this token to migrate the repositories from the Azure DevOps organization to GitHub.
This will be your only time that this personal access token will be presented to you. Make sure you’ve copied it someplace safe before clicking the Close button!
🛠️ Click the Close button.
When you close the Success! panel, you will be taken back to the Personal Access Tokens page. You will see the personal access token you just created listed there:
You now have a personal access token that Warp will use to connect to the Azure DevOps organization whose repositories will be migrated.
Let’s now generate a PAT for your GitHub account.
🛠️ Switch to GitHub, then click on your profile picture. Select Settings from the menu that appears.
You will be taken to the Settings page for your GitHub account:
🛠️ In the menu on the left side of the page, click on Developer settings (you may need to scroll down a bit).
This will take you to the Developer settings page:
🛠️ In the menu on the left side of the page, expand the Personal access tokens item, then select Tokens (classic).
You will end up at the Personal access tokens (classic) page:
🛠️ Click the Generate new token button, then select Generate new token (classic) from the menu that appears.
You will arrive at the New personal access token (classic) page, where you’ll need to provide enough information to create a new personal access token:
🛠️ Enter a name or some other text to help you identify the token in the Note field. To make it easier to identify, we suggest you include “Warp” in the name.
ℹ️ For the purposes of this Quickstart, we’ll leave the Expiration field at the default value of 30 days.
🛠️ Under Select scopes, check the following boxes, which will appear in this order:
repo
workflow
write:packages
delete:packages
🛠️ There are a few more items to check. Scroll down a little further...
🛠️ ...then check the following:
admin:org
admin:repo_hook
delete_repo
🛠️ Scroll to the bottom of the page. You’ll see this:
🛠️ Click the Generate token button.
You should now see this page, which will display the personal access token you just created:
🛠️ Just as you did with the personal access token in Azure DevOps, copy this new personal access token and save it in a safe place — preferably a password manager. Warp needs this token to migrate the repositories to GitHub.
Once again, this will be your only time that this personal access token will be presented to you. Make sure you’ve copied it someplace safe before closing this web page!
Now that you’ve generated personal access tokens for both your Azure DevOps organization and GitHub account, you need to make them available to Warp so that it can perform migrations, while securing them so that they are only available to Warp. You’ll do this by setting up a vault — an encrypted file that stores the personal access tokens, which Warp will decrypt with a vault key.
🛠️ Open a command-line terminal on your computer, using the Terminal application on macOS or Linux, or Command Prompt or PowerShell on Windows and change to the directory containing the cloned Migration HQ repository.
🛠️ Run the following command, which starts the Warp command-line application that sets up the vault:
You will see the “Welcome” text pictured below:
🛠️ Press the Enter or Return key to continue.
You will see the Configure Providers menu, which lets you add, update, and delete tokens for various source control providers:
🛠️ The default option, Add a New Provider, is the one you want. Press the Enter or Return key to select this option.
🛠️ Let’s add the personal access token for Azure DevOps first. Since Azure DevOps is the default option, simply press the Enter or Return key to select it.
You’ll see this text, which explains that you’re about to configure an Azure DevOps provider:
🛠️ Press the Enter or Return key to continue.
You will now be prompted to enter the personal access token you created in Azure DevOps:
🛠️ Paste your Azure DevOps personal access token into the text area marked Your PAT...
🛠️ ...then press the Enter or Return key to continue.
The next step is to specify the access scope for the Azure DevOps personal access token:
🛠️ Select Single organization access using the ⬆️ and ⬇️ keys, then press the Enter or Return key.
You’ll be asked to enter the Azure Devops organization slug, which you copied when you were creating the personal access token for your Azure DevOps organization. In this example, the slug is joey-ado-testing:
🛠️ Paste or enter the organization slug into the text area marked ado-organization-slug...
🛠️ ...then press the Enter or Return key to continue.
You’ll then be asked to specify the number of days until the token expires:
🛠️ Enter 30, then press the Enter or Return key.
Finally, you’ll be asked to confirm the information you’ve entered:
🛠️ Press y to confirm that the information is correct.
It’s time to add the personal access token for GitHub. You’ll see the Configure Providers menu again:
🛠️ Once again, the default option, Add a New Provider, is the one you want. Press the Enter or Return key to select this option.
🛠️ Select GitHub [Destination] using the ⬆️ and ⬇️ keys, then press the Enter or Return key.
You’ll see this text, which explains that you’re about to configure a GitHub destination:
🛠️ Press the Enter or Return key to continue.
You will now be prompted to enter the personal access token you created in GitHub:
🛠️ Paste your GitHub personal access token into the text area marked Your PAT...
🛠️ ...then press the Enter or Return key to continue.
You’ll be asked to enter the GitHub organization slug, which you copied when you were creating the personal access token for your GitHub organization.
In this example, the slug is Hypotheticorp5678:
🛠️ Paste or enter the organization slug into the text area marked destination-organization-slug, then press the Enter or Return key to continue.
You’ll then be asked to specify the number of days until the token expires:
🛠️ Enter 30, then press the Enter or Return key.
Finally, you’ll be asked to confirm the information you’ve entered:
🛠️ Press y to confirm that the information is correct.
You will return to the Configure Providers menu.
🛠️ Select Exit and Save Changes using the ⬆️ and ⬇️ keys, then press the Enter or Return key.
This will create the vault file, which needs to be committed and pushed to the Migration HQ repository. You will see this prompt:
🛠️ Use the default option, Yes, then press the Enter or Return key.
You will see the Save Your Vault Key prompt:
🛠️ Just as you did with the personal access token in Azure DevOps and GitHub, copy the vault key and save it in a safe place — preferably a password manager. You will need it to unlock the personal access tokens that were encrypted into the vault.
🛠️ After you have copied and saved the vault key, press the Enter or Return key to continue.
You’ll see the final message:
At this point:
The Azure DevOps and GitHub personal access tokens have been encrypted into the vault file (config/vault.age on macOS and Linux, config\vault.age on Windows)
The vault file has been committed and pushed to the Migration HQ repository.
The next step is to store the key for the vault file in the Migration HQ repository. This will allow the Warp GitHub Actions to access the personal access tokens you encrypted into the vault, which in turn will allow them to migrate your repositories from Azure DevOps to GitHub.
You could do this manually by copying the vault key and pasting it into the Migration HQ repository’s Secrets section. However, Warp provides a command-line application that will do this for you. Let’s use it.
🛠️ Run the following command, which starts the Warp command-line application that stores the vault key in the Migration HQ repository:
You’ll be greeted with the following text:
🛠️ Press the Enter or Return key to continue.
You’ll be prompted to enter your vault key:
🛠️ Paste the vault key into the text area...
🛠️ ...then press the Enter or Return key to continue.
The app will store your vault key into the Migration HQ repository’s secrets and display this message:
You should confirm that your vault key was successfully stored in Migration HQ by checking the repository’s Secrets section in GitHub:
🛠️ Open a browser tab or window to the Migration HQ repository in GitHub and click the Settings tab.
🛠️ In the menu on the left side of the page, select Secrets and variables to expand it, then select Actions.
You should see the Actions secrets and variables page for Migration HQ :
🛠️ Check the Repository secrets section and confirm that it contains a secret named PKFS_MASTER_KEY.
If you see the PKFS_MASTER_KEY secret, you have successfully stored the vault key in Migration HQ. If not, you should run the gh warp vault place command again.
The next step is to connect your Azure DevOps account to Warp. This will allow Warp to access the repositories you want to migrate from Azure DevOps to GitHub.
🛠️ Go back to the Warp browser tab or window. Make sure that you’re on the Connect Your Sources page shown above, then click the Check Credentials button near the lower right corner of the page.
The text in the Verify Credentials section will change to “We’re checking your Vault’s credentials. This will take a moment...”:
🛠️ While Warp is examining your vault, switch to the browser tab or window that you were using for the Migration HQ repository in GitHub:
🛠️ Select the Actions tab. This will display the list of Migration HQ’s workflows.
If you switched to the GitHub browser tab or window and clicked the Actions tab quickly enough, you should see a workflow with a spinning yellow icon named Warp Runner Agent. The yellow icon denotes that it is currently running. This workflow is using the vault key you stored in Migration HQ’s secrets to unlock the personal access tokens for Azure DevOps and GitHub.
🛠️ Wait until the spinning yellow icon is be replaced by a green checkmark. This means that the vault key was successfully used to unlock the personal access tokens for Azure DevOps and GitHub.
🛠️ Switch back to the browser tab or window for Warp:
You should see a section below Verify Credentials titled Your Vault. It should contain two items:
An item representing the Azure DevOps Organization containing the repositories you want to migrate, and
An item representing the GitHub organization where you want to migrate the repositories.
If you don’t see these items, click your browser’s Refresh button.
🛠️ Click the Next button.
You’ll arrive at the All Done! page, which marks the end of the process of configuring the project:
🛠️ Let’s check the project’s status. Click the Go to Dashboard button.
The Dashboard page shows the status of the project you just configured:
The Trends section displays the following statistics:
The number of repositories that Warp found in the Azure DevOps Organization,
the number of repositories that have been migrated to GitHub,
the average number of repositories that have been migrated per day, and
the overall progress of the migration, expressed as a percentage.
The text above the Trends section says “Tasks in Progress” and “Scanning your sources...” Warp is scanning your Azure DevOps organization for repositories. Let’s see this process in action.
🛠️ Switch to the browser tab or window for the Migrations HQ repository and select the Actions tab:
You should see a new workflow with a spinning yellow icon named Warp Runner Agent. The yellow icon denotes that it is currently running. This workflow is scanning the Azure DevOps organization for repositories.
🛠️ Wait for the Warp Runner Agent workflow to start and finish. You’ll know it’s finished when the spinning yellow icon is replaced by a green checkmark. The process may take a few minutes, depending on how many repositories are in your Azure DevOps organization.
🛠️ When the Warp Runner Agent has finished its tasks, switch back to the browser tab or window with the Warp Dashboard:
You should see the updated statistics on the Dashboard page. The number of repositories found in the Azure DevOps Organization should now be displayed.
If you don’t see a count of discovered Azure DevOps repositories, click your browser’s Refresh button.
So far, here’s what you’ve done:
Created a new projectGenerated personal access tokens for Azure DevOps and GitHub
Set up the vault
Stored the vault key in Migration HQ
Connected your Azure DevOps account to Warp
Scanned the Azure DevOps Organization for repositories.
It’s finally time to migrate a repository from Azure DevOps to GitHub!
🛠️ Switch to the browser tab or window with Migration HQ and select the Issues tab:
Warp creates an issue in the Migration HQ repository for every repository it finds in your Azure DevOps organization. These issues are used to manage the migration of repositories from Azure DevOps to GitHub.
🛠️ Click on the issue for the repository you want to migrate. In this example, we’re clicking on the issue named TailwindTraders-Website.
The page for the issue will appear:
The body of the issue — the part that contains a description and other notes about the issue — contains information assembled by Warp about the corresponding repository.
If you take a closer look at the body, you’ll see that it’s divided into the following subsections:
Migration Status: This section shows the current status of the migration. Since the migration hasn’t started yet, its status is not started.
Tasks: This section has a checklist of the tasks that need to be performed to migrate the repository. Warp will automatically check off the tasks as they are completed.
About: This lists basic information about the source repository, such as when its last commit was, how many commits it’s had in the past year, who its most active contributor was, and its size.
Source & Destination: This provides links to the source and the destination repositories.
Inventory: This shows information about the destination repository. Since the migration hasn’t started yet, this section simply says that the repository hasn”t been migrated yet.
It’s time to migrate!
🛠️ Scroll down the page to the comments section...
🛠️ ...and in the first comment, enter the following command:
In moments, Warp will reply with a follow-up comment announcing that the migration has started:
Depending on a number of factors, including the size of the repository and how many migrations Warp is performing at the same time, the migration may take a few to several minutes to complete.
🛠️ In the meantime, switch to the browser tab or windows for Migration HQ and click the Actions tab:
You should see a new workflow with a spinning yellow icon named Warp Runner Agent. The yellow icon denotes that it is currently running. This workflow is performing the task of migrating the repository from Azure DevOps to GitHub.
Eventually, the runner agent will complete its tasks, and its icon will change from spinning yellow to a green circle with a checkmark. This means that Warp has finished migrating the repository.
🛠️ Confirm that the repository has been migrated by clicking the Issues tab:
You’ll see the list of open issues. In our example, there are now only four open issues, where there were five originally. Migrating the repository closed its issue.
🛠️ Let’s look at the closed issues. Click on the Closed tab.
You’ll see the list of closed issues. It should contain the issue for the repository you just migrated:
🛠️ Examine the issue by clicking it:
When the issue page opens, you’ll see a number of changes:
The Migration Status section now shows a graphic indicating that the migration is complete.
The Migrate this repository’s comments to GitHub checkbox in the Tasks list is now checked.
The Source and Destination section now has links for both the source and destination repositories.
The Inventory section now shows information about the migrated repository.
🛠️ Scroll to the comments section:
You’ll see a new comment from Warp, complete with a link to the destination repository.
🛠️ Click on the link to visit the newly-migrated repository.
You’ll see the repository’s page — in GitHub! — with all of its files, branches, and commits:
When you started, the GitHub organization had a single repository: Migration HQ.
🛠️ Click on the organization’s name (near the top left corner of the page), followed by the Repositories tab.
You’ll see that the organization now has two repositories: Migration HQ and the repository you just migrated from Azure DevOps.
🙌 Congratulations! You’ve successfully migrated a repository from Azure DevOps to GitHub using Warp.
/migrate command.
/migrate command.
