Azure Pipelines YAML Schema Reference

YAML Schema Reference

This document provides a comprehensive reference for the YAML schema used in Azure Pipelines. Understand the structure and available options for defining your CI/CD pipelines.

Top-Level Schema Elements

trigger object | array | string

Defines the events that trigger a pipeline run. This can include CI triggers (e.g., pushes to branches) or scheduled triggers.

  • branches: Specifies branches to include or exclude for CI triggers.
  • paths: Specifies paths to include or exclude for CI triggers.
  • batchComplete: If true, the pipeline runs only when all CI jobs are completed.
  • batchPosted: If true, the pipeline runs when the first CI job is posted.
  • clearPostedImage: If true, the pipeline runs when the first CI job is posted.
  • branchesFilter: A list of branches to include or exclude.
  • pathFilter: A list of paths to include or exclude.
  • override: Overrides the default branch filter.
  • include: A list of branches or paths to include.
  • exclude: A list of branches or paths to exclude.
  • mainBranchOnly: If true, the pipeline only triggers for the main branch.
  • CI: If true, the pipeline triggers for CI events.
  • CD: If true, the pipeline triggers for CD events.
  • schedules: An array of schedule objects for scheduled triggers.

pool object

Specifies the agent pool where the job will run.

  • name: The name of the agent pool.
  • vmImage: The name of the virtual machine image to use for Microsoft-hosted agents (e.g., ubuntu-latest, windows-latest).
  • demands: A list of demands that the agent must satisfy.
  • poolId: The ID of the agent pool.

variables object | array

Defines variables that can be used throughout the pipeline.

  • name: The name of the variable.
  • value: The value of the variable.
  • [variableName]: Direct assignment of a variable.

stages array

A list of stages in the pipeline. Each stage represents a major phase of the deployment.

  • stage: The name of the stage.
  • dependsOn: Specifies the stages that this stage depends on.
  • condition: A condition that must be met for the stage to run.
  • jobs: A list of jobs within the stage.
  • variables: Stage-specific variables.

Stage Elements

jobs array

A list of jobs within a stage. Each job runs on an agent.

  • job: The name of the job.
  • pool: Specifies the agent pool for the job.
  • dependsOn: Specifies jobs or stages that this job depends on.
  • condition: A condition that must be met for the job to run.
  • steps: A list of steps to execute within the job.
  • variables: Job-specific variables.

Job Elements

steps array

A list of steps to execute within a job. Steps can be tasks, scripts, or other executable actions.

  • task: The name of a pre-defined task.
  • script: A script to execute.
  • bash: A bash script to execute.
  • pwsh: A PowerShell script to execute.
  • displayName: A friendly name for the step.
  • condition: A condition that must be met for the step to run.
  • inputs: Input parameters for a task.
  • name: The name of the step.
  • timeoutInMinutes: Timeout for the step.
  • continueOnError: Whether to continue if this step fails.

Example YAML Snippet


trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

variables:
  buildConfiguration: 'Release'

stages:
- stage: Build
  displayName: 'Build Application'
  jobs:
  - job: BuildJob
    displayName: 'Build'
    steps:
    - task: NuGetToolInstaller@1
      displayName: 'Use NuGet 5.8.4'

    - task: NuGetCommand@2
      displayName: 'Restore NuGet packages'
      inputs:
        restoreSolution: '**/*.sln'

    - task: VSBuild@1
      displayName: 'Build solution'
      inputs:
        solution: '**/*.sln'
        configuration: '$(buildConfiguration)'

- stage: Deploy
  displayName: 'Deploy Application'
  dependsOn: Build
  condition: succeeded('Build')
  jobs:
  - deployment: DeployWebApp
    displayName: 'Deploy to Web App'
    environment: 'Production'
    strategy:
      runOnce:
        deploy:
          steps:
          - script: echo Deploying to production...
            displayName: 'Deployment Script'

Common Tasks and Options

Azure Pipelines offers a rich set of built-in tasks for various operations, including:

Refer to the Azure Pipelines Tasks documentation for a complete list and detailed explanations of each task's inputs and outputs.

Conditions

Conditions allow you to control the execution of stages, jobs, and steps. Common condition functions include: