Migrating a Pipeline from Classic to YAML in Azure DevOps

Migrating a Pipeline from Classic to YAML in Azure DevOps

Migrating a pipeline from the classic editor to YAML in Azure Pipelines involves translating the existing pipeline configuration (which is usually in a UI-based format) into a YAML definition. Below is a step-by-step guide to help you through the migration process.

Steps to Migrate a Classic Pipeline to YAML.

1. Analyze the Classic Pipeline

1. Navigate to the Classic Pipeline:

   • Go to your Azure DevOps project.

   • Select Pipelines from the left menu.

   • Choose the pipeline you want to migrate (usually, it's under "Pipelines" –> "Classic").

2. Review Stages, Jobs, and Steps:

   • Identify each stage, job, and step in the classic pipeline.

   • Note tasks and actions like build steps, test runs, and deployments.

2. Create a New YAML Pipeline

1. Create a New Pipeline:

   • Navigate to Pipelines –> + New Pipeline.

   • Select YAML and choose a repository (or create a new one).

2. Define Pipeline Structure in YAML: Create a YAML pipeline based on the tasks and stages of the classic pipeline.

3. Convert Classic Pipeline Elements to YAML

Classic Pipeline Elements vs. YAML Mapping:

• Stages in Classic → stages: in YAML.

• Jobs in Classic → jobs: within a stage in YAML.

• Steps in Classic → steps: within a job in YAML.

• Tasks in Classic → Tasks defined in the steps: block in YAML.

Example Migration:

Classic Pipeline:

xxxxxxxxxx
19
1
trigger: 
2
- main
3
stages:
4
   - stage: Build
5
    jobs:
6
     - job: Build
7
        steps:
8
         - task: DotNetCoreCLI@2
9
            inputs:
10
              command: build
11
              projects: '**/.csproj'
12
   - stage: Test
13
    jobs:
14
     - job: Test
15
        steps:
16
         - task: DotNetCoreCLI@2
17
            inputs:
18
              command: test
19
              projects: '**/.Tests/.csproj'

YAML Pipeline:

xxxxxxxxxx
19
1
trigger:
2
- main
3
stages:
4
   - stage: Build
5
    jobs:
6
     - job: BuildJob
7
        steps:
8
         - task: DotNetCoreCLI@2
9
            inputs:
10
              command: build
11
              projects: '**/.csproj'
12
   - stage: Test
13
    jobs:
14
     - job: TestJob
15
        steps:
16
         - task: DotNetCoreCLI@2
17
            inputs:
18
              command: test
19
              projects: '**/.Tests/.csproj'

4. Test and Verify

1. Test the Pipeline:

   • Run the YAML pipeline by committing and pushing the changes to your repository.

   • Monitor pipeline execution and check that stages, jobs, and steps function as expected.

2. Validate Outputs: Ensure that outputs, artifacts, and deployment outcomes match the classic pipeline's behavior.

5. Deploy the YAML Pipeline

After testing and verifying that the pipeline works as expected, update the pipeline to replace the classic pipeline with the new YAML configuration.

6. Update Dependencies

If your classic pipeline relies on external dependencies (e.g., custom tasks or extensions), ensure these are available or redefined within your YAML pipeline.

7. Key Considerations for Migrating

1. Complexity: Migrating pipelines with complex logic (e.g., dependent stages or multiple nested jobs) may require significant rework.

2. Task Availability: Ensure that custom tasks or extensions used in the classic pipeline are supported or have equivalent YAML-based tasks.

3. Variables and Secrets: Properly manage and migrate variables and secrets to YAML configurations.

Key Considerations:

1. Template Usage: Consider using reusable templates (Stage Templates, Job Templates) to avoid redundancy.

2. Performance: YAML pipelines may have different performance characteristics depending on the complexity of tasks and stages.

8. Limitations

While migrating from classic to YAML, there are a few limitations and challenges to be aware of:

1. Limited Classic Features Some advanced features in classic pipelines (e.g., approvals, manual intervention, custom tasks, and third-party extensions) may require customization in YAML pipelines.

2. Debugging and Logging Debugging in YAML pipelines is different from classic pipelines. You must rely on logs provided by the pipeline execution.

3. External Tools and Tasks Some third-party tools or older custom tasks might not have YAML-based equivalents. In such cases, you may need to write custom scripts or use alternative tasks.

4. YAML Learning Curve YAML syntax can be a challenge for those new to writing YAML configurations, especially for pipelines with complex logic.

9. Benefits of Migrating to YAML

1. Version Control: Pipelines are stored as YAML in your repository.

2. Reusability: Easily create reusable templates for stages and jobs.

3. Automation: YAML pipelines can be easily triggered via CI/CD pipelines, using webhooks, or from other repositories.

4. Infrastructure as Code: Pipelines are treated as code, making them easier to maintain and collaborate on.

5. Consistency: Standardized structure for defining CI/CD workflows.