Azure Pipelines Multi-stage YAML Patterns: Templates, Approval Gates, Conditional, Matrix, Deployment Strategy

A Multi-stage YAML pipeline is a CI/CD pattern that defines multiple stages (Build / Test / Deploy) in a single YAML file, and it is the de facto standard for modern Production CI/CD. Supported by both Azure Pipelines and GitHub Actions, it is a core topic of AZ-400 exam domain 3 (40-45% weight). This article covers the hierarchy, Templates, Approval Gates, Conditionals, Matrix, and Deployment Strategy comprehensively.

Hierarchy (Stage / Job / Step / Task)

In production, a typical stage design is Build (multi-OS build with parallel Jobs) → Test (parallel Jobs) → Deploy (Sequential Dev → Stage → Prod).

Basic Multi-stage YAML Example

trigger:
  branches:
    include:
      - main

stages:
  - stage: Build
    jobs:
      - job: BuildJob
        pool:
          vmImage: ubuntu-latest
        steps:
          - task: NodeTool@0
            inputs:
              versionSpec: '20.x'
          - script: npm install
          - script: npm run build
          - publish: dist
            artifact: webapp

  - stage: DeployDev
    dependsOn: Build
    condition: succeeded()
    jobs:
      - deployment: DeployToDev
        environment: dev
        strategy:
          runOnce:
            deploy:
              steps:
                - download: current
                  artifact: webapp
                - task: AzureWebApp@1
                  inputs:
                    azureSubscription: 'AzureServiceConnection'
                    appName: 'myapp-dev'

  - stage: DeployProd
    dependsOn: DeployDev
    condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
    jobs:
      - deployment: DeployToProd
        environment: prod  # Approval Gate 設定済み
        strategy:
          runOnce:
            deploy:
              steps:
                - download: current
                  artifact: webapp
                - task: AzureWebApp@1
                  inputs:
                    azureSubscription: 'AzureServiceConnection'
                    appName: 'myapp-prod'

Modularize with Templates

Templates are reusable components of YAML pipelines.

Four Kinds of Templates

Step Template Example

# templates/build-node.yml
parameters:
  - name: nodeVersion
    type: string
    default: '20.x'
  - name: workingDirectory
    type: string

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: ${{ parameters.nodeVersion }}
  - script: npm install
    workingDirectory: ${{ parameters.workingDirectory }}
  - script: npm run build
    workingDirectory: ${{ parameters.workingDirectory }}

Calling a Template

steps:
  - template: templates/build-node.yml
    parameters:
      nodeVersion: '20.x'
      workingDirectory: 'frontend'

In the enterprise, 10-20 standard Templates manage 100+ Pipelines, dramatically reducing maintenance cost.

Approval Gates and Manual Validation

Azure Pipelines Setup

1. Create an Environment (e.g. 'prod')
2. Under Environment Approvals and Checks, specify Approvers (1-3 required)
3. Reference environment: prod from a Pipeline Stage
4. On Stage execution, Approvers are notified by email and wait in the Azure DevOps UI
5. Deploy runs after approval

GitHub Actions Setup

1. Repository Settings → Environments → create 'prod'
2. Specify Required Reviewers
3. Reference environment: prod in a Workflow Job

Typical Gate Configurations

• Production: 2 approvers (CISO + Engineering Lead) + business hours only (Time Window) + Azure Monitor alert quiet for the previous hour
• DR Site: 1 approver
• Dev / Stage: auto-deploy (no Approval)

Conditional Execution and Variables

Key Techniques

1. Conditions: condition clause runs a Stage / Job / Step conditionally
2. Expressions: $[] for Runtime evaluation, ${{ }} for Compile-time evaluation
3. Variables (Pipeline-defined): variables: clause declares them
4. Variable Groups: centrally managed in the Azure DevOps Library (e.g. per-environment connection strings)
5. Output Variables: passing values between Jobs
6. Conditional Variables: per-environment variable values
7. Runtime Parameters: parameters chosen by users at Pipeline runtime

Example: Deploy only on the main branch

condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))

Example: Runtime Parameters

parameters:
  - name: deployTarget
    displayName: Deploy Target
    type: string
    default: 'all'
    values:
      - 'all'
      - 'us-only'
      - 'jp-only'

stages:
  - stage: DeployUS
    condition: in(${{ parameters.deployTarget }}, 'all', 'us-only')
    # ...
  - stage: DeployJP
    condition: in(${{ parameters.deployTarget }}, 'all', 'jp-only')
    # ...

Matrix Strategy

A feature that runs multiple combinations (OS × Runtime version × Configuration) in parallel.

Azure Pipelines Matrix

jobs:
  - job: Build
    strategy:
      matrix:
        Debug_x86:
          configuration: Debug
          platform: x86
        Debug_x64:
          configuration: Debug
          platform: x64
        Release_x86:
          configuration: Release
          platform: x86
        Release_x64:
          configuration: Release
          platform: x64
      maxParallel: 4
    steps:
      - script: msbuild /p:Configuration=$(configuration) /p:Platform=$(platform)

Typical Use Cases

• Cross-platform OSS testing (a Node.js library tested in parallel across 3 OS × 3 versions = 9; 10 min → 1.5 min)
• Container multi-arch builds (amd64, arm64, arm/v7 in parallel)
• Visual Studio C++ multi-config builds
• AWS / Azure / GCP multi-cloud deploys

Deployment Strategy

Canary Strategy Example

jobs:
  - deployment: DeployCanary
    environment: prod
    strategy:
      canary:
        increments: [10, 30, 60, 100]  # 段階的トラフィックシフト
        preDeploy:
          steps:
            - script: echo "Pre-deploy check"
        deploy:
          steps:
            - task: KubernetesManifest@1
              inputs:
                action: deploy
                strategy: canary
                percentage: $(strategy.increment)
        postRouteTraffic:
          steps:
            - script: ./scripts/verify-canary.sh
        on:
          failure:
            steps:
              - script: ./scripts/rollback.sh
          success:
            steps:
              - script: echo "Canary success"

Typical Selection

• Simple web apps → RunOnce + Deployment Slot Swap
• Stateful VM Scale Sets → Rolling
• Microservices risk management → Canary (1% → 10% → 50% → 100%)
• Mission-critical → Blue-Green (instant rollback via Slot swap)

Variable Groups and Key Vault Integration

Variable Groups: shared variable sets across multiple Pipelines (managed in the Azure DevOps Library).

Key Vault Integration

• Enable 'Link secrets from an Azure key vault' on the Variable Group
• Map Azure Key Vault Secrets directly
• Secret values bypass Azure DevOps and are pulled dynamically from Key Vault at Pipeline run time
• Pipeline edits are unnecessary even when Secrets are rotated

Example

variables:
  - group: KeyVaultGroup  # Key Vault Reference 設定済み

jobs:
  - job: Deploy
    steps:
      - script: |
          echo "Connecting to DB..."
        env:
          DB_CONNECTION_STRING: $(DB_CONNECTION_STRING)

Output Variables (Passing Values Between Jobs)

jobs:
  - job: JobA
    steps:
      - script: |
          echo "##vso[task.setvariable variable=buildNumber;isOutput=true]20260524-001"
        name: setBuildNumber

  - job: JobB
    dependsOn: JobA
    variables:
      buildNum: $[ dependencies.JobA.outputs['setBuildNumber.buildNumber'] ]
    steps:
      - script: echo "Build Number from Job A: $(buildNum)"

Operational Best Practices

1. Build → Test → Deploy as a standard Stage structure
2. Centrally manage organization-wide logic with Pipeline Templates
3. Manage Secrets via Variable Groups + Key Vault integration
4. Secure production releases with Environment + Approval Gates
5. Secret-less authentication via Workload Identity Federation
6. Shorten CI time in parallel with Matrix Strategy
7. Manage production release risk with Canary or Blue-Green
8. Per-environment behavior control via Conditional Execution
9. Deployment flexibility with Runtime Parameters
10. Version-control Pipeline-as-Code in Git

Related Certifications

• AZ-400 (DevOps Engineer Expert): the flagship cert here, probed deeply in domain 3 (40-45% weight)
• AZ-204 (Developer Associate): CI/CD from the developer angle
• AZ-104 (Administrator): fundamentals
• AZ-305 (Solutions Architect Expert): DevOps strategy

Frequently Asked Questions

Technical information in this article is based on the Azure Pipelines YAML Schema Documentation. This article is not an official Microsoft Corporation product and has no affiliation or sponsorship with Microsoft. Microsoft, Azure, Azure DevOps, and GitHub are trademarks of the Microsoft group of companies. Information is based on publicly available official material as of May 24, 2026. Always check the official pages for the latest information.