Cheat sheet to migrate generic v1 templates to v2

Posted by Willy-Peter Schaub on Fri 01 March 2024

Questioning the recommended approach to upgrades and the use of generic templates.

We shared our v2 CI/CD blueprints for Azure Pipelines as open source, which include our generic templates that we created as a temporary solution to replace the classic Azure Build Pipelines for continuous integration (CI). They are helpful to begin with YAML-based build pipelines and link them with classic Azure Release Pipelines, but not our preferred approach. We will explain more about that later.

v1 versus v2 generic template

First, let us answer our engineer's question of how to migrate from our v1 generic templates to the v2 versions. The image below compares v1 with v2, as at 2024-02-22. The only differences (all highlighted in yellow) are minor cleanups and:

v1 --> v2

Make the right choice!

Before you proceed with the migration, you need to determine WHY you should be using the generic template. Here is a simple checklist to help you with the decision:

  1. Is there a v2 CI/CD blueprint for your application type? If yes, use the v2 CI/CD blueprint. We are phasing out the classic Azure Pipelines and so should you.
  2. Else, Do you have to use a Classic Azure Release Pipeline? If yes, use the single-job v2 generic template for your CI/Build pipeline.
  3. Do you need the multi-job v2 generic template? NO, we strongly recommend keeping it simple and only using the single-job v2 generic template. You should only use the multi-job template in rare situations and try to avoid it as it makes things more complicated and can put pressure on your Azure DevOps agents. See Part 5: Pipelines - Blueprints to fuel consistency and enablement for an explanation of the two types of generic templates.

OK back to: How to migrate from v1 to v2 generic build-only template?

Migrate v1 --> v2, option 1 – move your pipeline to v2 (recommended)

  1. Create a new pipeline, using the single-job v2 generic template.
  2. Look for TODO placeholders and migrate (copy-paste) the code from your v1 to your new v2-based Azure Pipeline.
  3. Reconnect your classic Azure Release Pipeline to the new v2-based Azure Pipeline.
  4. Validate the new pipeline.
  5. Deprecate (delete) your old v1-based pipeline.


Migrate v1 --> v2, option 2 – upgrade your v1 pipeline

Using the comparison between v1 and v2 as per image above, update your v1 pipeline and upgrade it to the v2 pipeline format, following these basic steps:

  1. Update template repo name from CeSTemplates to CeBlueprints.
  2. Update template repo name, by appending .v2.
  3. Remove variables section and add checkout logic under at the beginning of the stage definition.
  4. Rename /Templates/ to templates/.
  5. Use either dotnet or other for applicationType.
  6. Validate the updated pipeline.

Hope our internal "how to" discussions are interesting and add value to the open source v2 CI/CD blueprints.