Moving your Azure DevOps build pipelines to your code repository

I am a proponent of “configuration as code” and “infrastructure as code”. For years I considered build and release pipeline setup as the missing piece of the puzzle. In the later releases, (which includes the rebranding to Azure DevOps), Microsoft implemented a feature where the build pipeline definition lives in your code repository together with your code. Yay! But what about your existing “legacy” VSTS projects? In this post, we’ll walk through the process of migrating those existing projects.

Creating azure-pipeline.yml file

The first step is generating the build script definition file, azure-pipelines.yml, from your existing legacy build configuration in DevOps (VSTS). Luckily, DevOps will help you with this. Use the View YAML button in the top right corner:

From the popup that appears when you click the button, copy the contents to the clipboard:

Then create a file named azure-pipelines.yml, and place it in your code repository and check it in. We’re done with the first step!

Adjusting azure-pipeline.yml

The View YAML functionality in DevOps brought us a long way, but we’re not quite there yet, so we need to make some adjustments. The format of the file is yaml, so I advice you to use an editor with syntax checking for this format. Better yet, if you use Visual Studio code, the Azure Pipelines extension will validate against a schema:

Adding variables definitions

So, what do we need to change in the generated file? DevOps gave us some hints when generating the YAML:

For some reason, the generation did not create the variable definitions for the variables used in the script. So, we need to add a variables entry in the azure-pipelines.yaml file:

Adding triggers (or other options)

If you have customized your build triggers in your existing build setup, you need to manually set these in azure-pipelines.yml. For example, if you build from a branch other than the default branch (typically master ), and you have a monorepo with several projects, you can define the trigger like so:

Then, when done editing azure-pipelines.yml, we are ready to take it for a spin.

Create a new build definition

Go to the Azure DevOps portal for your project, and create a new build definition. You’ll see a screen like this:

Select the YAML template under the ‘configuration as code’ category.

We’ll select the Configuration as code — YAML option. Then, we need to point it to our build script file (if you have a single project repository, and have your source in DevOps, it will automatically be detected if you place it in the repository root with the default file name):

Add the path, relative to repository root, for the build configuration file.

Now, select Save & queue to try out the build.

But alas, there is something wrong! It seems that there is a bug in the DevOps YAML generation (hopefully, this will be fixed, so you might not experience this issue):

Generated VM image reference is wrong.

It seems that the YAML file generation picked the wrong reference for the vmImage setting. This is quite easy to correct in the azure-pipelines.yml file, changing the generated value Hosted Ubuntu 1604 to 'Ubuntu-16.04':

And it works!

Further customization

We have now gone through the steps that we need for most build configurations. But often, as the project progresses we need to make changed to, and extend the build configuration. For information about the build file format, use Microsoft’s comprehensive documentation here.