lvictorerod/yamlizr

Azure DevOps Designer-to-YAML Pipeline CLI CodeGen Tool

Yamlizr - Azure DevOps Designer-to-YAML Pipeline Conversion Tool

This tool was created when there was no means of exporting a designer/classic build/release 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 function 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, which the official tool does not. It also allows the conversion of every single Build/Release definition en-masse, so much less clicking! Then you can then cut/copy/paste/manipulate the generated YAML steps as required to fit into a build and/or deployment pipeline unique to your own requirements.

yamlizr is a .NET 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 6.0 SDK.
• From a command line shell install the tool; dotnet tool update --global yamlizr

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

• Azure DevOps .NET Client Libraries
• AzurePipelinesToGitHubActionsConverter
• YamlDotNet
• CommandLineUtils
• ShellProgressBar

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.