Techniques: Converting Azure Pipelines from GUI to YAML

If you’re a long-time Azure DevOps user, you probably have a large collection of pipelines created using the GUI editor. However, if making extensive use of Azure Pipelines, you may find YAML a more appealing option for maintenance & portability. Recently, my team switched to YAML for all of our future pipelines. The first of these was created to satisfy a fairly simple use case: running a QA suite independent from the build. Here are a few notes on the process...

From 30k ft, converting to YAML pipelines involves creating one (or more) .yml files that live in an application’s code repo. You’ll simply tell the Azure DevOps pipeline to point to that file. The contents of the .yml file contain a scripted out version of the steps in your GUI pipeline. We’ll go in depth on that in a sec…

But first, it’s good to cover a few important design decisions:

1. Which repo & directory will the .yml file live?

2. Which Agent Pool will be used to run the pipeline?

3. What should trigger the pipeline? i.e. Should it run whenever code is committed to the repo? Should it run only on demand?

Before we begin with the scripting, two “gotchas” to be aware of: One is syntax. YAML is very particular to indentation, such that even a stray space will invalidate the file. It’s important you work in an editor that offers syntax highlighting (such as VS Code). Another gotcha is that while Azure DevOps offers a “code snippet” feature to convert GUI pipeline Steps into YAML, this by itself is incomplete. You’ll need to add additional initialization properties to the YAML file, which we’ll cover below.

Now for the fun part. In this section we’ll convert a simple GUI pipeline into its YAML equivalent:

First, create the .yml file to describe the pipeline:

1. Create a blank pipeline.yml file in the repo of the application you’re testing.

2. Add the initialization content shown in this template.

3. Now refer to your GUI pipeline and extract the content of the step(s) by clicking “View YAML”.

4. Paste that into the .yml template you created. It should look something like this.

5. Commit the code to the repo & push upstream.

Now initialize the pipeline in Azure DevOps:

1. Use the “New pipeline” wizard (Step 1, Step 2, Step 3, Step 4, Step 5)

2. REALLY IMPORTANT! After saving the new pipeline, Azure DevOps issues a default name that matches the repo. This is not always desirable. If you need to change the name, go to:

   1. Edit

   2. “…” menu > Triggers

   3. YAML

At this point, you can now do a test run of the pipeline and compare it the your GUI version. The results should be equivalent. This exercise demonstrates the relative ease of YAML pipeline maintenance, as future updates will be done in code, rather than via the GUI editor.

If you’re new to YAML, I hope this post helps shed light on the promise of the format, and points you in the direction of more holistic CI/CD configuration with YAML piplines, where builds and releases can also be managed this way.