Migrating from Azure DevOps Pipelines to GitHub Actions can be difficult, particularly if you have a large project with complex build definitions. The GitHub CLI Migration Extension, on the other hand, can make the process easier. In this blog post, we will walk through the steps involved in migrating from Azure DevOps Pipelines to GitHub Actions using this extension.

BEFORE WE GET STARTED

Before we begin, it is important to note that migrating from Azure DevOps to GitHub is a massive task (at least if you have 20+ pipelines), and you should always plan your migration meticulously. You don't have to migrate all pipelines at once, but living with two systems can be a pain, so keep it as short as possible.

INSTALL GITHUB CLI AND MIGRATION EXTENSION

Let's get this migration started. The GitHub CLI migration extension can only be used after the GitHub CLI has been installed. The GitHub CLI, which can be installed on a variety of platforms, provides a command-line interface for interacting with GitHub repositories. To install the GitHub CLI, go to https://cli.github.com and follow the instructions on the page.

Next, open up terminal (or command prompt) and install the gh-actions-importer extension

You can verify that the extension works by running following command:

PAT TOKENS

Two PAT tokens are required to complete the migration. One is for GitHub, and the other is for Azure DevOps.

To generate a GitHub token, follow the instructions at https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-personal-access-token-classic.

To function, the GitHub token requires workflow scope.

See https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows#create-a-pattern for Azure DevOps.

The Azure DevOps token requires the following permissions to work:

• Agents Pool:Read
• Build: Read
• Code: Read
• Release: Read
• Service Connections:Read
• Task Groups:Read
• Variable Groups:Read

Now we have everything set, and we can configure the GH CLI extension by running the configure command.

Answer the wizard's questions and use the default GitHub and Azure DevOps base URLs. Don't include the names of your organisations.

Even though we just installed the actions importer, we need to update it. I'm not sure why this is required, but without it, the migration will almost certainly fail. Use the following command to update:

Now we're ready to run the migration simulation and see how well this tool handles all of our pipeline quirks. Use the Audit command with the output directory to run the simulation.

The output-dir must be a relative path. Giving an absolute path, such as c:temp, will not work. This command traverses your Azure DevOps pipelines for the specified project and generates a report detailing how well it can convert pipelines into GitHub Actions. The report provides some guidance, but it is not entirely accurate. The report may state that the importer is capable of migrating the pipeline, but it will not work at GitHub without minor modifications.

If you use **/*.csproj paths in your Azure DevOps Pipelines, for example, the importer will bring that setting into GitHub Actions and it will not work. You have two options for dealing with this: Extend the importer or manually change the paths on GitHub to MyProject/MyProject.csproj.

MIGRATION

Finally, we can run our importer and begin the migration process. The tool's best feature is that it will generate a pull request for the imported action. It will not simply create items in your GitHub repository. Having the ability to create a pull request is a powerful tool for inspecting the final result, possibly creating an extension, and rerunning the migration. Your coworkers can also review pull requests, which gives you more security and control over what you're doing.

The migrate azure-devops pipeline command is used to perform the migration. You must supply the pipeline-id (if you only want to run it for one pipeline), the GitHub target URL, and the logs directory. You can easily find the pipeline id by editing a pipeline in Azure DevOps and inspecting the URL.

EXTENDING THE IMPORTER

If you need to migrate multiple pipelines, it may not be feasible to fix all migration errors in a GitHub pull request one by one. Fortunately, we can extend the importer and write our own Ruby scripts to convert those inconvenient paths into proper GitHub Action paths. I'll write a guide on how to extend the importer later, but you should be able to find some good examples on GitHub.

POSSIBLE CONSIDERATIONS

Migrating Azure DevOps pipelines to GitHub can be a time-consuming process. You must carefully plan your migration and then decide which tools to use. You may want to consider upgrading pipelines into more appropriate actions rather than simply using the lift and shift method. If you want to do the latter, GitHub actions-importer is an excellent tool. Good luck with your move!