Migrate a pipeline from classic to YAML

Why migrate

YAML lives in the repository, so the pipeline is versioned, branched, reviewed and rolled back with the code it builds. A classic pipeline is edited in a UI, with no branch, no pull request and no diff.

The behavioural differences that bite

A team migrating a multi-job classic release and expecting the same ordering will find their jobs running concurrently. That single difference causes more migration incidents than any other.

A safe migration

1. Export the classic definition to YAML where the tooling supports it, as a starting draft — not a finished pipeline.
2. Translate task groups into templates. There is no equivalent, so this is a rewrite, not a mapping.
3. Re-express ordering explicitly with dependsOn, because you no longer get sequence for free.
4. Run both in parallel against the same commits and compare outputs before retiring the classic definition.
5. Move variables into the YAML or into variable groups, keeping secrets in the group or Key Vault.

Step 4 is the one teams skip and regret: the classic pipeline is the only oracle for what "correct" means, and once it is deleted, any difference in behaviour is undiagnosable.

Primary sources

• https://learn.microsoft.com/en-us/azure/devops/pipelines/migrate/from-classic-to-yaml