Moving Task Groups to YAML Builds in Azure DevOps

The Pipelines in Azure DevOps now support defining build configurations with YAML files. This is a huge advantage if your project is anything like my team’s and requires you to reproduce old builds.

When I started making the move to YAML builds, I ran into some frustration with task groups, which are core building blocks of our build pipeline. There’s no simple way to export task groups to YAML, and the documentation about doing it manually is vague at best.

After much experimenting, I found that a few key steps helped me create a simple workflow for converting our task groups into YAML build definitions. Here are my best tips for making the jump.

1. Export Task Groups as JSON

When you’re looking at the details of a given task group, you’ll see an option to export as JSON. The exported task group shows you all of the information needed to run your task. This same information is available in the interface, but I found it to be far more accessible in the JSON format when making the switch to YAML.

One thing to notice is that exporting as JSON will export every key/value pair, including default values. This can sometimes make it look like you’ll need to define many values in your YAML, when you really just need to define two or three and let the rest use the default. Fortunately, there are ways to figure out most of the default values so you can keep your YAML file concise. See the Use the Task Catalog section below for more on that.

2. Create Templates

In YAML builds, templates are the equivalent of task groups. (At the time I’m writing this, the Azure DevOps documentation doesn’t call this out directly. I had to dig through GitHub to find it. Microsoft has plans to document this better in the future.)

When creating a template, you make a separate YAML file with a set of tasks you want to reuse. To run all of those tasks, all you have to do is reference the template. If you need to run the same set of tasks on different pipelines with a separate YAML file for each pipeline, you can have each YAML file reference the template for those tasks.

This was probably the most important piece of using YAML builds for my use case. If your pipeline is built heavily on task groups, templates are going to be a key piece of your YAML build definition.

3. Use the Task Catalog

There’s a task catalog that has information about every task available in Azure Pipelines. Once you find the name of your task, view the documentation for that specific task to see an example of the YAML syntax. This documentation points out which parameters are optional and which are required.

Documentation on optional parameters often states the default value. I found this to be really valuable for keeping my YAML files as concise as possible.

4. Use the Task ID for Custom Tasks

The project I was working on used some add-on NuGet packages for tasks. I couldn’t find any information on this in the task catalog, so it presented a bit of a challenge. It turns out each task in the JSON file has an ID associated with it. This ID can be used in your YAML file instead of the task name. The syntax for defining a task would usually be TaskName@Version#, but in this case, use TaskID@Version# instead.

I’ll be the first to admit that it’s not pretty. The ID is a long string, and I had to include all key/value pairs since I didn’t know what the defaults were. It was still worth it to me, but this is something you’ll want to weigh for your project.

If you have any questions about moving your task groups to YAML builds, leave a comment below. I’d be happy to help out!