Convert Azure Pipelines YAML to GitHub Actions YAML

A project to create a conversion tool to make migrations between Azure Pipelines YAML and GitHub Actions YAML easier. As GitHub Actions becomes more popular, it's clear that a migration tool will be useful to move workloads to GitHub.

How to use

We built a website that uses this module at: https://pipelinestoactions.azurewebsites.net/.
You can also use the NuGet package

Example:

The Azure Pipelines YAML to build a dotnet application on ubuntu:

trigger:
- main
variables:
  buildConfiguration: Release
jobs:
- job: Build
  displayName: Build job
  pool: 
    vmImage: ubuntu-latest
  steps: 
  - script: dotnet build WebApplication1/WebApplication1.Service/WebApplication1.Service.csproj --configuration $(buildConfiguration) 
    displayName: dotnet build webapp

In GitHub Actions:

on: 
  push:
    branches:
    - main
env:
  buildConfiguration: Release
jobs:
  Build:
    name: Build job
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v1
    - name: dotnet build webapp
      run: dotnet build WebApplication1/WebApplication1.Service/WebApplication1.Service.csproj --configuration ${{ env.buildConfiguration }}";

Current builds running

The table below shows current, functioning YML files that run on a regular schedule to regression test the YAML produced | Language | Azure Pipelines | GitHub Actions | | -- | -- | -- | | .NET Core WebAPI | | | | .NET Framework Desktop | | | | Ant | | | | Maven | | | | NodeJS | | | | Python | | | | Ruby | | |

How this works

Currently this only supports one-way migrations from Azure Pipelines to GitHub Actions. There are functions to deserialize Azure Pipelines, and serialize and deserialize GitHub Actions. While this is translating many steps, there are nearly infinite combinations, therefore most of the focus has been supporting the basic .NET pipelines. Even if steps can't convert, the pipeline should. Check the issues for incomplete items, or the TODO's in the source code.

Yaml can be challenging. The yaml wikipedia page does a very good job of laying out the rules, but when we are talking about converting yaml to C#, there are a few things to know:

1. Use a good editor - Visual Studio Code has a decent YAML extension (https://marketplace.visualstudio.com/items?itemName=docsmsft.docs-yaml), or if using Visual Studio, enable spaces with CTRL+R,CTRL+W. The GitHub and Azure DevOps in-browser editors are decent too.
2. String arrays (string[]) are useful for lists (e.g -job). Note both of the following pieces of code for triggers are effectively the same (although the YamlDotNet serializer does not currently support the single line 'sequence flow' format)

trigger: [main,develop]

trigger:
- main
- develop

3. The dictonary object (dictonary<string,string>) is useful for dynamic key value pairs, for example, variables

variables:
  MY_VAR: 'my value'
  ANOTHER_VAR: 'another value'

The C# definition for a dictonary looks like:

Dictionary<string, string> variables = new Dictionary<string, string>
{
    { "MY_VAR", "my value" },
    { "ANOTHER_VAR", "another value" }
};

4. Just about everything else can be a string or object. Here is an example of a simple job:

- job: Build
  displayName: 'Build job'
  pool:
    vmImage: ubuntu-latest

public string job { get; set; }
public string displayName { get; set; }
public Pool pool { get; set; }

5. Yaml is wack. The white spaces can destroy you, as the errors returned are often not helpful at all. Take lots of breaks. In the end YAML is worth it - I promise!

Current limitations

There are a number of Azure Pipeline features that don't currently match up well with a GitHub feature, and hence, these migrate with a change in functionality (e.g. parameters become variables and stages become jobs), or not at all (e.g. deployment strategies/environments). As/if these features are added to Actions, we will build in the conversions

Stages

Stages are converted to jobs. For example, a job "JobA" in a stage "Stage1", becomes a job named "Stage1_JobA"

Azure Pipelines YAML

stages:
- stage: Build
  displayName: 'Build Stage'
  jobs:
  - job: Build
    displayName: 'Build job'
    pool:
      vmImage: windows-latest
    steps:
    - task: PowerShell@2
      inputs:
        targetType: 'inline'
        script: |
         Write-Host "Hello world!"

  - job: Build2
    displayName: 'Build job 2'
    pool:
      vmImage: windows-latest
    steps:
    - task: PowerShell@2
      inputs:
        targetType: 'inline'
        script: |
         Write-Host "Hello world 2!"

GitHub Actions YAML

jobs:
  Build_Stage_Build:
    name: Build job
    runs-on: windows-latest
    steps:
    - uses: actions/checkout@v1
    - run: 
        Write-Host "Hello world!"
      shell: powershell
  Build_Stage_Build2:
    name: Build job 2
    runs-on: windows-latest
    steps:
    - uses: actions/checkout@v1
    - run: 
        Write-Host "Hello world 2!"
      shell: powershell

Parameters

Parameters become variables

Azure Pipelines YAML

parameters: 
  buildConfiguration: 'Release'
  buildPlatform: 'Any CPU'

jobs:
  - job: Build
    displayName: 'Build job'
    pool:
      vmImage: windows-latest
    steps:
    - task: PowerShell@2
      displayName: 'Test'
      inputs:
        targetType: inline
        script: |
          Write-Host "Hello world ${{parameters.buildConfiguration}} ${{parameters.buildPlatform}}"

GitHub Actions YAML

env:
  buildConfiguration: Release
  buildPlatform: Any CPU
jobs:
  Build:
    name: Build job
    runs-on: windows-latest
    steps:
    - uses: actions/checkout@v1
    - name: Test
      run: Write-Host "Hello world ${{ env.buildConfiguration }} ${{ env.buildPlatform }}"
      shell: powershell

RunOnce deployment strategy and deployment jobs

The strategy and deployment job is consolidated to a job, with the strategy removed, as there is no GitHub equivalent

Azure Pipelines YAML

jobs:
  - deployment: DeployInfrastructure
    displayName: Deploy job
    environment: Dev
    pool:
      vmImage: windows-l