Migrate a pipeline from classic to YAML in Azure Pipelines

Migrating your Azure Pipelines definitions from the Classic Editor to YAML unlocks version control, peer reviews, and repeatable workflows. By storing the pipeline as code alongside your application, you gain granular change history, easier rollbacks, and seamless integration with GitHub or Azure Repos.

Why Use YAML Pipelines?

Version your pipeline in source control
Enable pull-request reviews for CI/CD changes
Reuse templates and parameters across projects
Support complex, multi-stage workflows
Align with DevSecOps best practices

Pre-Migration Checklist

Before you begin, review and document every aspect of your existing Classic Pipeline:

Task	Description
Review pipeline steps	Inventory GUI tasks, environment variables, triggers, and deployment steps
Identify inline scripts & variables	Find PowerShell/Bash blocks and secret/environment variable usage
Check for unsupported marketplace tasks	Note any tasks not available in YAML and research alternatives or extensions
Plan testing strategy	Define a branch or isolated project to validate your new YAML pipeline before production

Migration Process

Follow these steps to convert a Classic pipeline stage into YAML.

1. Export or View Generated YAML

In the Classic pipeline, locate the Terraform deployment step and view its YAML equivalent. For example:

variables:
  terraformstoragegroup: 'terraform'
  terraformstorageaccount: 'terraform'
steps:
  - task: AzureCLI@1
    displayName: 'Azure CLI to deploy required Azure resources'
    inputs:
      azureSubscription: 'MCT'
      scriptLocation: 'inlineScript'
      inlineScript: |
        # Create Azure resource group
        az group create --location westus --name $(terraformstoragegroup)

        # Create Azure storage account
        az storage account create --name $(terraformstorageaccount) \
          --resource-group $(terraformstoragegroup) \
          --location westus \
          --sku Standard_LRS

2. Create a New YAML Pipeline

Copy the generated snippet into a new azure-pipelines.yml file. Customize triggers, variables, and steps to fit your environment:

trigger:
  branches:
    include:
      - main

pool:
  vmImage: 'ubuntu-latest'

variables:
  terraformstoragerg: 'terraformrg'
  terraformstorageaccount: 'terraformstorage09834d9'

steps:
  - task: AzureCLI@1
    displayName: 'Azure CLI to deploy required Azure resources'
    inputs:
      azureSubscription: 'MCT'
      scriptLocation: 'inlineScript'
      inlineScript: |
        # Create resource group
        az group create --location westus --name $(terraformstoragerg)

        # Create storage account
        az storage account create --name $(terraformstorageaccount) \
          --resource-group $(terraformstoragerg) \
          --location westus \
          --sku Standard_LRS

        # Create storage container
        az storage container create --name terraform --account-name $(terraformstorageaccount)

        # Retrieve storage account keys
        az storage account keys list \
          --resource-group $(terraformstoragerg) \
          --account-name $(terraformstorageaccount)

Use the Validate feature in the Azure Pipelines UI to catch syntax errors before running the pipeline.

The image illustrates a step-by-step migration process for validating and testing a YAML pipeline, showing a menu selection for "Validate" and a confirmation that the pipeline is valid, followed by a "Run" option.

Iterate on your YAML until it passes validation and your test runs succeed. Repeat for each Classic task to fully migrate your build or release pipeline.

Challenges and Solutions

Migrating real-world pipelines often surfaces these challenges:

Challenge	Solution
Secure secret management	Use Azure DevOps Library, Variable Groups, or Azure Key Vault
Unsupported or custom tasks	Explore the Azure DevOps Marketplace for community extensions
Complex multi-stage flows	Leverage YAML templates, parameters, and `extends` syntax for modular pipelines

The image outlines common challenges and solutions in software development, including managing secrets, handling complex deployments, ensuring CI/CD best practices, and dealing with unsupported tasks.

Best Practices

Review and replicate every Classic step in YAML
Validate and test in an isolated branch before merging
Use templates and reusable modules for consistency
Document pipeline changes via pull requests

References

Watch Video

Optimize pipeline concurrency for performance and cost

Analyze pipeline load to determine agent configuration and capacity

Introduction

Configure Activity Traceability and Flow of Work

Configure Collaboration & Communication

Work with Azure Repos and GitHub

Configuring and Managing Repositories

Design and Implement Pipeline Automation

Design and Implement Pipelines

Implementing an Orchestration Automation Solution

Design and Implement Deployments

Design and Implement Infrastructure as Code (IaC)

Maintain Pipelines

Design and Implement Authentication and Authorization Methods

Design and Implement a Strategy for Managing Sensitive Information in Automation

Implement Security and Validate Code Bases for Compliance

Configure Monitoring for a DevOps Environment

Analyze Metrics

Branching Strategies for Source Code

Design and Implement a Package Management Strategy

Migrate a pipeline from classic to YAML in Azure Pipelines

Why Use YAML Pipelines?

Pre-Migration Checklist

Migration Process

1. Export or View Generated YAML

2. Create a New YAML Pipeline

Challenges and Solutions

Best Practices

References

Watch Video

​Why Use YAML Pipelines?

​Pre-Migration Checklist

​Migration Process

​1. Export or View Generated YAML

​2. Create a New YAML Pipeline

​Challenges and Solutions

​Best Practices

​References

Watch Video

Why Use YAML Pipelines?

Pre-Migration Checklist

Migration Process

1. Export or View Generated YAML

2. Create a New YAML Pipeline

Challenges and Solutions

Best Practices

References