Yamlizr - Azure DevOps Designer-to-YAML Pipeline CLI

This tool was created in the summer of 2020 when there was no means of exporting a definition to YAML. As of November 2020 there is a new Export to YAML feature which allows you to export a Build pipeline to YAML with a single click. This official tool probably covers more edge cases than this CLI for Build pipelines. Where this CLI still has benefits is that it also converts Release definitions to YAML, it also allows the conversion of every single Build/Release definition en-masse which developers can then customise to fit their unique deployment needs.

yamlizr is a .NET Core Global Tool which converts Azure DevOps Classic Designer Build/Release Definitions and any referenced Task Groups en-masse into their YAML Pipeline or GitHub Action equivalent.

The tool itself uses the Azure DevOps .NET Client Libraries to pre-cache relevant data from your Azure DevOps organisation/account. This data includes build/release definitions, task groups, tasks/extensions data and variable groups. This Azure DevOps data is converted into Azure DevOps Pipeline objects (stages/jobs/steps/variables) which are then persisted to YAML using the YamlDotNet library.

This is not a delicate tool to create perfectly constructed YAML pipelines. Instead consider it to be a hammer which will spawn as many YAML files as possible and from this YAML you can pick/choose and copy/paste the relevant stages/jobs/steps/variables into your own preferred YAML CI/CD deployment architecture.

Also... there is an optional switch whereby the tool can pass the Azure DevOps Pipeline objects into the AzurePipelinesToGitHubActionsConverter library (by @samsmithnz) and export your pipelines as GitHub Actions YAML.

Disclaimer: Do not consider any of the YAML generated by this tool to be 'production ready'. Do your own testing/research and post any issues and/or make a PR!

Installation/Set-up

Create a Personal Access Token (PAT) with the following scopes/permissions;

Scope Permission

Build Read

Deployment Groups Read & Manage

Release Read

Task Groups Read

Variable Groups Read
Download and install either .NET Core 3.1 SDK or .NET 5.0 SDK.
From a command line shell install the tool; dotnet tool update --global yamlizr

Scope	Permission
Build	Read
Deployment Groups	Read & Manage
Release	Read
Task Groups	Read
Variable Groups	Read

CLI Operation

To generate YAML files in the c:/temp/myoutputfolder output folder execute the following command;

yamlizr generate -pat <your PAT here> -org <your AzDO organisation> -proj <your AzDO project> -out c:/temp/myoutputfolder

For context-sensitive help execute;

yamlizr --help

Optional switches;

--inline merge the tasks from task groups into the steps of the calling job instead of creating additional template files.
--githubactions generate GitHub Actions workflows via AzurePipelinesToGitHubActionsConverter.
--filter filter build/release definitions (if you want to use a more granular approach).

To generate both Azure Pipelines and GitHub Actions YAML for a build definition called 'wibble-CI' and a release definition called 'wibble-CD';

yamlizr generate -pat <your PAT here> -org <your AzDO organisation> -proj <your AzDO project> -out c:/temp/myoutputfolder --filter wibble --githubactions

All YAML files generated are output into sub-folders of a project folder, i.e. using the above example of -o c:/temp/myoutputfolder the following folders are created;

c:/temp/myoutputfolder/<your AzDO project>/AzureDevOpsBuilds/*.yml
c:/temp/myoutputfolder/<your AzDO project>/AzureDevOpsReleases/*.yml
c:/temp/myoutputfolder/<your AzDO project>/AzureDevOpsTaskGroups/*.yml
c:/temp/myoutputfolder/<your AzDO project>/GitHubBuilds/*.yml
c:/temp/myoutputfolder/<your AzDO project>/GitHubReleases/*.yml

Core Dependencies

Misc Tips

The NuGet package includes SourceLink which enables you to jump inside the library and debug the API yourself. By default Visual Studio 2017/2019 does not allow this and will pop up an message "You are debugging a Release build of...", to disable this message go into the Visual Studio debugging options and un-check the 'Just My Code' option (menu path, Tools > Options > Debugging).

Known Issues

ShellProgressBar gives random formatting problems.
--parallelism command line option for faster processing is a bit buggy so disabled.
Various YAML structures are 'missing', PR's welcome.

Feedback/Issues

Please post any issues or feedback here.

vmcbaptista/yamlizr