Azure Pipelines YAML Complete Guide: Stages/Jobs/Steps, Templates, Variable Groups, Approval Gates

Azure Pipelines is the build and release automation service in Azure DevOps Services, defining CI/CD pipelines as YAML in a Pipelines as Code style. Microsoft offers it as the flagship CI/CD service alongside GitHub Actions, and it is the de facto standard for organizations on Azure DevOps Services. This article comprehensively covers Azure Pipelines YAML structure, Templates, Variable Groups, Environments, and Workload Identity Federation.

Basic Structure of a YAML Pipeline

Azure Pipelines YAML is defined as a hierarchy.

Minimal Sample: Hello World

trigger:
  branches:
    include:
      - main

pool:
  vmImage: ubuntu-latest

steps:
  - script: echo "Hello, Azure Pipelines!"
    displayName: 'Print greeting'

Choosing Between Stages, Jobs, and Steps

Stages

• Large logical blocks (Build → Test → Deploy to Dev → Deploy to Prod)
• Stages run sequentially (configurable dependencies)
• Each stage can have an Approval Gate

Jobs

• Parallel execution units within a stage
• One job per agent
• Useful for multi-platform builds across multiple OSes

Steps

• Sequential execution units within a job
• The smallest execution unit

Multi-stage Pipeline Example

stages:
  - stage: Build
    jobs:
      - job: BuildJob
        steps:
          - script: npm install
          - script: npm run build
          - publish: dist
            artifact: webapp

  - stage: DeployDev
    dependsOn: Build
    jobs:
      - deployment: DeployToDev
        environment: dev
        strategy:
          runOnce:
            deploy:
              steps:
                - download: current
                  artifact: webapp
                - task: AzureWebApp@1
                  inputs:
                    azureSubscription: 'AzureServiceConnection'
                    appName: 'myapp-dev'
                    package: '$(Pipeline.Workspace)/webapp'

  - stage: DeployProd
    dependsOn: DeployDev
    jobs:
      - deployment: DeployToProd
        environment: prod
        strategy:
          runOnce:
            deploy:
              steps:
                - download: current
                  artifact: webapp
                - task: AzureWebApp@1
                  inputs:
                    azureSubscription: 'AzureServiceConnection'
                    appName: 'myapp-prod'
                    package: '$(Pipeline.Workspace)/webapp'

Pipeline Templates

Pipeline Templates are reusable YAML pipeline components, in three flavors:

• Stage Templates: reuse an entire stage (e.g. a standard build stage)
• Job Templates: reuse at the job level (e.g. a standard test job)
• Step Templates: reuse a sequence of steps (e.g. NuGet install + Build)

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 the Template

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

Variables and Variable Groups

Ways to Define Variables

• Inline in the pipeline: variables: { appName: 'myapp' }
• Variable Group: centrally managed in the Azure DevOps Library
• Variable Template: a reusable variable set
• Key Vault integration: map secrets directly from Azure Key Vault

Key Vault Integration Example

variables:
  - group: KeyVaultGroup  # Azure DevOps Library で Key Vault Reference 設定済み

jobs:
  - job: Deploy
    steps:
      - script: |
          echo "Database connection: $(DB_CONNECTION_STRING)"
        env:
          DB_CONNECTION_STRING: $(DB_CONNECTION_STRING)

With Key Vault integration, secret values never sit in Azure DevOps - they are fetched dynamically from Key Vault at pipeline runtime. No pipeline changes are needed when secrets are rotated, making this a mandatory pattern for production.

Environments and Approval Gates

Environments logically manage deployment targets (Dev/Stage/Prod) in Azure DevOps. The following can be configured on each Environment:

• Approval: Required Reviewers (1-3 mandatory approvers)
• Gates: branch restriction, time window, Azure Monitor alerts, ServiceNow ticket checks
• Resources: link Kubernetes / VM Resources to the Environment

For a Deploy Stage to a Production Environment, compose multi-gate logic like 'requires 2 approvers', 'deploy only outside business hours', and 'no Azure Monitor alerts in the last hour' to ship safely. Environments also retain deploy history, providing audit trails of who deployed what and when. This is a mandatory capability for SOC2 / ISO 27001 compliance.

Service Connections and Workload Identity Federation

Service Connections centrally manage authentication from Azure DevOps to external systems (Azure, GitHub, Docker, Kubernetes).

Evolution of Azure Authentication

1. Service Principal + Secret (legacy, requires rotation)
2. Service Principal + Certificate (moderate)
3. Workload Identity Federation (WIF) (modern recommendation, no secrets)

WIF launched in Azure Pipelines in 2023. You configure a Federated Credential on the Service Principal and authenticate to Azure with OIDC tokens. Secret and certificate management is fully eliminated, dropping CI/CD secret-leak risk to zero. See Managed Identity vs Service Principal for details. For new Azure DevOps projects, WIF is the only correct choice and the industry standard.

Deployment Strategies

Best Practices

1. Always version-control your YAML (history and review via Git)
2. Ensure reusability with Templates (managed centrally in a shared repository)
3. Variable Groups + Key Vault integration (hardened secret management)
4. Environments + Approval Gates (safe production releases)
5. Workload Identity Federation (secretless CI/CD)
6. Self-hosted Agents for secure environments (don't run sensitive IaC on public agents)
7. Version-controlled artifacts (centralize nuget/npm/maven in Azure Artifacts)
8. Keep pipeline runtime under 30 minutes (split or parallelize longer runs)
9. Failure notifications (Teams / Slack integration)
10. Lint Pipeline as Code (use the azure-pipelines-vscode extension)

Azure Pipelines vs GitHub Actions

Related Certifications

• AZ-400 (DevOps Engineer Expert): the headline certification for this area, tested deeply in Domain 3 (Build and Release Pipelines, 40-45%).
• AZ-104 (Administrator): fundamentals of deploying Azure resources.
• AZ-204 (Developer Associate): CI/CD from a developer's perspective.
• AZ-305 (Solutions Architect Expert): DevOps strategy from an architect's perspective.
• SC-100 (Cybersecurity Architect Expert): DevSecOps.

Frequently Asked Questions

The technical information in this article is based on the Azure Pipelines Documentation. This article is not an official Microsoft Corporation product and has no affiliation or sponsorship. Microsoft, Azure, Azure DevOps, and GitHub are trademarks of the Microsoft group of companies. Information reflects official public materials as of May 24, 2026. Always confirm the latest details on the official pages.