Convert Classic Azure Pipelines to Version-Controlled YAML

Translate Classic Pipeline Components to YAML

Key Concepts

Azure Pipelines supports automating builds and deployments. A classic pipeline is built using a visual, point-and-click designer in the Azure DevOps portal. In contrast, a YAML pipeline is defined by a code file (a YAML file) stored directly in your application's source code repository. Migrating to YAML makes your pipeline definition modular, easier to reproduce, and trackable through version control, just like your application code.

Migration Process

The migration from a classic to a YAML pipeline follows a structured process. First, you must analyze your existing classic pipeline to identify all its key components, such as the specific build or deployment tasks it runs, any variables it uses, and the triggers that cause it to start. Next, you map each of these elements to its equivalent YAML syntax. For example, a task in the classic designer becomes a task: block in YAML, and a variable becomes a variables: entry.

Task Versions

When mapping tasks, you must pay attention to the correct task version. Each task, like the AzureFunctionApp task used to deploy a function, has specific versions (e.g., @1 or @2). You need to choose the version that matches the functionality you used in the classic pipeline and ensure your YAML syntax includes this version number. Using the wrong version can lead to errors or missing features in your new pipeline.

Create Modular YAML Pipeline Files

After mapping, you author the complete YAML configuration file. This file should be placed in your repository, typically in a folder like .azuredevops. The goal is to create a modular definition where each stage, job, and step is clearly organized. You then validate the new pipeline by running it. A successful run that produces the same outcome as your classic pipeline confirms that the migration maintains functional parity.