YAML schema reference

Azure Pipelines

Here's a detailed reference guide to Azure Pipelines YAML pipelines, including a catalog of all supported YAML capabilities, and the available options.

The best way to get started with YAML pipelines is through the quickstart guide. After that, to learn how to configure your YAML pipeline the way you need it to work, see conceptual topics such as Build variables and Jobs.

To learn how to configure your YAML pipeline the way you need it to work, see conceptual topics such as Build variables and Jobs.

Pipeline structure

Pipelines are made of one or more stages describing a CI/CD process. Stages are the major divisions in a pipeline: "build this app", "run these tests", and "deploy to pre-production" are good examples of stages.

Stages consist of one or more jobs, which are units of work assignable to a particular machine. Both stages and jobs may be arranged into dependency graphs: "run this stage before that one" or "this job depends on the output of that job".

Jobs consist of a linear series of steps. Steps can be tasks, scripts, or references to external templates.

This hierarchy is reflected in the structure of the YAML file.

  • Pipeline
    • Stage A
      • Job 1
        • Step 1.1
        • Step 1.2
        • ...
      • Job 2
        • Step 2.1
        • Step 2.2
        • ...
    • Stage B
      • ...

For simpler pipelines, not all of these levels are required. For example, in a single-job build, you can omit the containers for "stages" and "jobs" since there are only steps. Also, many options shown here are optional and have good defaults, so your YAML definitions are unlikely to include all of them.

Pipelines are made of one or more jobs describing a CI/CD process. Jobs are units of work assignable to a particular machine. Jobs may be arranged into dependency graphs, for example: "this job depends on the output of that job".

Jobs consist of a linear series of steps. Steps can be tasks, scripts, or references to external templates.

This hierarchy is reflected in the structure of the YAML file.

  • Pipeline
    • Job 1
      • Step 1.1
      • Step 1.2
      • ...
    • Job 2
      • Step 2.1
      • Step 2.2
      • ...

For single-job pipelines, you can omit the container "jobs" since there are only steps. Also, many options shown here are optional and have good defaults, so your YAML definitions are unlikely to include all of them.

Conventions

Conventions used in this topic:

  • To the left of : are literal keywords used in pipeline definitions.
  • To the right of : are data types. These can be primitives like string or references to rich structures defined elsewhere in this topic.
  • [ datatype ] indicates an array of the mentioned data type. For instance, [ string ] is an array of strings.
  • { datatype : datatype } indicates a mapping of one data type to another. For instance, { string: string } is a mapping of strings to strings.
  • | indicates there are multiple data types available for the keyword. For instance, job | templateReference means either a job definition or a template reference are allowed.

YAML basics

This document covers the schema of an Azure Pipelines YAML file. To learn the basics of YAML, see Learn YAML in Y Minutes. Note: Azure Pipelines doesn't support all features of YAML, such as anchors, complex keys, and sets.

Pipeline

name: string  # build numbering format
resources:
  containers: [ containerResource ]
  repositories: [ repositoryResource ]
variables: { string: string } | [ variable | templateReference ]
trigger: trigger
pr: pr
stages: [ stage | templateReference ]

If you have a single stage, you can omit stages and directly specify jobs:

# ... other pipeline-level keywords
jobs: [ job | templateReference ]

If you have a single stage and a single job, you can omit those keywords and directly specify steps:

# ... other pipeline-level keywords
steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]
name: string  # build numbering format
resources:
  containers: [ containerResource ]
  repositories: [ repositoryResource ]
variables: { string: string } | [ variable | templateReference ]
trigger: trigger
pr: pr
jobs: [ job | templateReference ]

If you have a single job, you can omit the jobs keyword and directly specify steps:

# ... other pipeline-level keywords
steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]

Learn more about multi-job pipelines, using containers and repositories in pipelines, triggers, variables, and build number formats.

Stage

A stage is a collection of related jobs. By default, stages run sequentially, starting only after the stage ahead of them has completed.

stages:
- stage: string  # name of the stage, A-Z, a-z, 0-9, and underscore
  displayName: string  # friendly name to display in the UI
  dependsOn: string | [ string ]
  condition: string
  variables: { string: string } | [ variable | variableReference ] 
  jobs: [ job | templateReference]

Learn more about stages, conditions, and variables.

Job

A job is a collection of steps to be run by an agent or on the server. Jobs can be run conditionally, and they may depend on earlier jobs.

jobs:
- job: string  # name of the job, A-Z, a-z, 0-9, and underscore
  displayName: string  # friendly name to display in the UI
  dependsOn: string | [ string ]
  condition: string
  strategy:
    parallel: # parallel strategy, see below
    matrix: # matrix strategy, see below
    maxParallel: number # maximum number of matrix jobs to run simultaneously
  continueOnError: boolean  # 'true' if future jobs should run even if this job fails; defaults to 'false'
  pool: pool # see pool schema
  workspace:
    clean: outputs | resources | all # what to clean up before the job runs
  container: containerReference # container to run this job inside
  timeoutInMinutes: number # how long to run the job before automatically cancelling
  cancelTimeoutInMinutes: number # how much time to give 'run always even if cancelled tasks' before killing them
  variables: { string: string } | [ variable | variableReference ] 
  steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]
  services: { string: string | container } # container resources to run as a service container

Learn more about variables, steps, pools, and server jobs,.

Note

If you have only one stage and one job, you can use single-job syntax as a shorter way to describe the steps to run.

Container reference

container is supported by jobs.

container: string # Docker Hub image reference or resource alias
container:
  image: string  # container image name
  options: string  # arguments to pass to container at startup
  endpoint: string  # endpoint for a private container registry
  env: { string: string }  # list of environment variables to add

Strategies

matrix and parallel are mutually-exclusive strategies for duplicating a job.

Matrix

Matrixing generates copies of a job with different inputs. This is useful for testing against different configurations or platform versions.

strategy:
  matrix: { string1: { string2: string3 } }
  maxParallel: number

For each string1 in the matrix, a copy of the job will be generated. string1 is the copy's name and will be appended to the name of the job. For each string2, a variable called string2 with the value string3 will be available to the job.

Note

Matrix configuration names must contain only basic Latin alphabet letters (A-Z, a-z), numbers, and underscores (_). They must start with a letter. Also, they must be 100 characters or less.

Optionally, maxParallel specifies the maximum number of simultaneous matrix legs to run at once.

If not specified or set to 0, no limit will be applied.

If not specified, no limit will be applied.

Parallel

This specifies how many duplicates of the job should run. This is useful for slicing up a large test matrix. The VS Test task understands how to divide the test load across the number of jobs scheduled.

strategy:
  parallel: number

Steps

Steps are a linear sequence of operations that make up a job. Each step runs in its own process on an agent and has access to the pipeline workspace on disk. This means environment variables are not preserved between steps but filesystem changes are.

steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]

See the schema references for script, bash, pwsh, powershell, checkout, task, and step templates for more details about each.

Variables

Hardcoded values can be added directly, or variable groups can be referenced. Variables may be specified at the pipeline, stage, or job level.

For a simple set of hardcoded variables:

variables: { string: string }

To include variable groups, switch to this list syntax:

variables:
- name: string # name of a variable
  value: any # value of the variable
- group: string # name of a variable group

name/value pairs and groups can be repeated.

Variables may also be included from templates.

Template references

Note

Be sure to see the full template expression syntax (all forms of ${{ }}).

You can export reusable sections of your pipeline to a separate file. These separate files are known as templates. Azure Pipelines supports four kinds of templates:

You can export reusable sections of your pipeline to a separate file. These separate files are known as templates. Azure DevOps Server 2019 supports two kinds of templates:

Templates may themselves include other templates. Azure Pipelines supports a maximum of 50 unique template files in a single pipeline.

Stage templates

A set of stages can be defined in one file and used multiple places in other files.

In the main pipeline:

- template: string # name of template to include
  parameters: { string: any } # provided parameters

And in the included template:

parameters: { string: any } # expected parameters
stages: [ stage ]

Job templates

A set of jobs can be defined in one file and used multiple places in other files.

In the main pipeline:

- template: string # name of template to include
  parameters: { string: any } # provided parameters

And in the included template:

parameters: { string: any } # expected parameters
jobs: [ job ]

See templates for more about working with job templates.

Step templates

A set of steps can be defined in one file and used multiple places in another file.

In the main pipeline:

steps:
- template: string  # reference to template
  parameters: { string: any } # provided parameters

And in the included template:

parameters: { string: any } # expected parameters
steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]

See templates for more about working with templates.

Variable templates

A set of variables can be defined in one file and referenced several times in other files.

In the main pipeline:

- template: string            # name of template file to include
  parameters: { string: any } # provided parameters

And in the included template:

parameters: { string: any }   # expected parameters
variables: [ variable ]

Resources

Container resource

Container jobs let you isolate your tools and dependencies inside a container. The agent will launch an instance of your specified container, then run steps inside it. The container resource lets you specify your container images.

Service containers run alongside a job to provide various dependencies such as databases.

resources:
  containers:
  - container: string  # identifier (A-Z, a-z, 0-9, and underscore)
    image: string  # container image name
    options: string  # arguments to pass to container at startup
    endpoint: string  # endpoint for a private container registry
    env: { string: string }  # list of environment variables to add
    ports: [ string ] # ports to expose on the container
    volumes: [ string ] # volumes to mount on the container

Repository resource

If your pipeline has templates in another repository, you must let the system know about that repository. The repository resource lets you specify an external repository.

resources:
  repositories:
  - repository: string  # identifier (A-Z, a-z, 0-9, and underscore)
    type: enum  # see below
    name: string  # repository name (format depends on `type`)
    ref: string  # ref name to use, defaults to 'refs/heads/master'
    endpoint: string  # name of the service connection to use (for non-Azure Repos types)

Type

Pipelines support two types of repositories, git and github. git refers to Azure Repos Git repos. If you choose git as your type, then name refers to another repository in the same project. For example, otherRepo. To refer to a repo in another project within the same organization, prefix the name with that project's name. For example, OtherProject/otherRepo.

If you choose github as your type, then name is the full name of the GitHub repo including the user or organization. For example, Microsoft/vscode. Also, GitHub repos require a service connection for authorization.

Triggers

Push trigger

A trigger specifies what branches will cause a continuous integration build to run. If left unspecified, pushes to every branch will trigger a build. Learn more about triggers and how to specify them. Also, be sure to see the note about wildcards in triggers.

There are three distinct options for trigger: a list of branches to include, a way to disable CI triggering, and the full syntax for ultimate control.

List syntax:

trigger: [ string ] # list of branch names

Disable syntax:

trigger: none # will disable CI builds entirely

Full syntax:

trigger:
  batch: boolean # batch changes if true (the default); start a new build for every push if false
  branches:
    include: [ string ] # branch names which will trigger a build
    exclude: [ string ] # branch names which will not
  tags:
    include: [ string ] # tag names which will trigger a build
    exclude: [ string ] # tag names which will not
  paths:
    include: [ string ] # file paths which must match to trigger a build
    exclude: [ string ] # file paths which will not trigger a build
trigger:
  batch: boolean # batch changes if true (the default); start a new build for every push if false
  branches:
    include: [ string ] # branch names which will trigger a build
    exclude: [ string ] # branch names which will not
  paths:
    include: [ string ] # file paths which must match to trigger a build
    exclude: [ string ] # file paths which will not trigger a build

Important

When you specify a trigger, only branches that are explicitly configured to be included will trigger a pipeline. Includes are processed first, and then excludes are removed from that list. If you specify an exclude but don't specify any includes, nothing will trigger.

PR trigger

A pull request trigger specifies what branches will cause a pull request build to run. If left unspecified, pull requests to every branch will trigger a build. Learn more about pull request triggers and how to specify them.

Important

YAML PR triggers are only supported in GitHub and Bitbucket Cloud. If you are using Azure Repos Git, you can configure a branch policy for build validation in order to trigger your build pipeline for validation.

Important

YAML PR triggers are only supported in GitHub. If you are using Azure Repos Git, you can configure a branch policy for build validation in order to trigger your build pipeline for validation.

There are three distinct options for pr: a list of branches to include, a way to disable PR triggering, and the full syntax for ultimate control.

List syntax:

pr: [ string ] # list of branch names

Disable syntax:

pr: none # will disable PR builds entirely; will not disable CI triggers

Full syntax:

pr:
  autoCancel: boolean # indicates whether additional pushes to a PR should cancel in-progress runs for the same PR. Defaults to true
  branches:
    include: [ string ] # branch names which will trigger a build
    exclude: [ string ] # branch names which will not
  paths:
    include: [ string ] # file paths which must match to trigger a build
    exclude: [ string ] # file paths which will not trigger a build

Important

When you specify a pr trigger, only branches that are explicitly configured to be included will trigger a pipeline. Includes are processed first, and then excludes are removed from that list. If you specify an exclude but don't specify any includes, nothing will trigger.

Scheduled trigger

YAML scheduled triggers are not available in this version of Azure DevOps Server or TFS. You can use scheduled triggers in the classic editor.

A scheduled trigger specifies a schedule on which branches will be built. If left unspecified, no scheduled builds will occur. Learn more about scheduled triggers and how to specify them.

schedules:
- cron: string # cron syntax defining a schedule
  displayName: string # friendly name given to a specific schedule
  branches:
    include: [ string ] # which branches the schedule applies to
    exclude: [ string ] # which branches to exclude from the schedule
  always: boolean # whether to always run the pipeline or only if there have been source code changes since the last run. The default is false.

Important

When you specify a scheduled trigger, only branches that are explicitly configured to be included are scheduled for a build. Includes are processed first, and then excludes are removed from that list. If you specify an exclude but don't specify any includes, no branches will be built.

Pool

pool specifies which pool to use for a job of the pipeline. It also holds information about the job's strategy for running.

Full syntax:

pool:
  name: string  # name of the pool to run this job in
  demands: string | [ string ]  ## see below
  vmImage: string # name of the vm image you want to use, only valid in the Microsoft-hosted pool

If you're using a Microsoft-hosted pool, then choose an available vmImage.

If you're using a private pool and don't need to specify demands, this can be shortened to:

pool: string # name of the private pool to run this job in

Learn more about conditions and timeouts.

Demands

demands is supported by private pools. You can check for existence of a capability or a specific string like this:

pool:
  demands: [ string ]

Server

server specifies a server job. Only server tasks such as manual intervention or invoking an Azure Function can be run in a server job.

This will make the job run as a server job rather than an agent job.

pool: server

Script

script is a shortcut for the command line task. It will run a script using cmd.exe on Windows and Bash on other platforms.

steps:
- script: string  # contents of the script to run
  displayName: string  # friendly name displayed in the UI
  name: string  # identifier for this step (A-Z, a-z, 0-9, and underscore)
  workingDirectory: string  # initial working directory for the step
  failOnStderr: boolean  # if the script writes to stderr, should that be treated as the step failing?
  condition: string
  continueOnError: boolean  # 'true' if future steps should run even if this step fails; defaults to 'false'
  enabled: boolean  # whether or not to run this step; defaults to 'true'
  timeoutInMinutes: number
  env: { string: string }  # list of environment variables to add

Learn more about conditions and timeouts.

Bash

bash is a shortcut for the shell script task. It will run a script in Bash on Windows, macOS, or Linux.

steps:
- bash: string  # contents of the script to run
  displayName: string  # friendly name displayed in the UI
  name: string  # identifier for this step (A-Z, a-z, 0-9, and underscore)
  workingDirectory: string  # initial working directory for the step
  failOnStderr: boolean  # if the script writes to stderr, should that be treated as the step failing?
  condition: string
  continueOnError: boolean  # 'true' if future steps should run even if this step fails; defaults to 'false'
  enabled: boolean  # whether or not to run this step; defaults to 'true'
  timeoutInMinutes: number
  env: { string: string }  # list of environment variables to add

Learn more about conditions and timeouts.

Pwsh

pwsh is a shortcut for the PowerShell task with pwsh set to true. It will run a script in PowerShell Core on Windows, macOS, or Linux.

steps:
- pwsh: string  # contents of the script to run
  displayName: string  # friendly name displayed in the UI
  name: string  # identifier for this step (A-Z, a-z, 0-9, and underscore)
  errorActionPreference: enum  # see below
  ignoreLASTEXITCODE: boolean  # see below
  failOnStderr: boolean  # if the script writes to stderr, should that be treated as the step failing?
  workingDirectory: string  # initial working directory for the step
  condition: string
  continueOnError: boolean  # 'true' if future steps should run even if this step fails; defaults to 'false'
  enabled: boolean  # whether or not to run this step; defaults to 'true'
  timeoutInMinutes: number
  env: { string: string }  # list of environment variables to add

Learn more about conditions and timeouts.

PowerShell

powershell is a shortcut for the PowerShell task. It will run a script in PowerShell on Windows.

steps:
- powershell: string  # contents of the script to run
  displayName: string  # friendly name displayed in the UI
  name: string  # identifier for this step (A-Z, a-z, 0-9, and underscore)
  errorActionPreference: enum  # see below
  ignoreLASTEXITCODE: boolean  # see below
  failOnStderr: boolean  # if the script writes to stderr, should that be treated as the step failing?
  workingDirectory: string  # initial working directory for the step
  condition: string
  continueOnError: boolean  # 'true' if future steps should run even if this step fails; defaults to 'false'
  enabled: boolean  # whether or not to run this step; defaults to 'true'
  timeoutInMinutes: number
  env: { string: string }  # list of environment variables to add

Learn more about conditions and timeouts.

Error action preference

Unless specified, the task defaults the error action preference to stop. The line $ErrorActionPreference = 'stop' is prepended to the top of your script.

When the error action preference is set to stop, errors will cause PowerShell to terminate and return a non-zero exit code. The task will also be marked as Failed.

errorActionPreference: stop | continue | silentlyContinue

Ignore last exit code

By default, the last exit code returned from your script will be checked and, if non-zero, treated as a step failure. The system will append your script with:

if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE }

If you don't want this behavior, set ignoreLASTEXITCODE to true.

ignoreLASTEXITCODE: boolean

Learn more about conditions and timeouts.

Publish

publish is a shortcut for the Publish Pipeline Artifact task. It will publish (upload) a file or folder as a pipeline artifact that can be consumed by other jobs and pipelines.

steps:
- publish: string # path to a file or folder
  artifact: string # artifact name

Learn more about publishing artifacts.

Download

download is a shortcut for the Download Pipeline Artifact task. It will download one or more artifacts associated with the current run to $(Pipeline.Workspace). It can also be used to disable automatic downloading of artifacts in classic release and deployment jobs.

steps:
- download: [ current | none ] # disable automatic download if "none"
  artifact: string # artifact name
  patterns: string # patterns representing files to include

Learn more about downloading artifacts.

Checkout

Non-deployment jobs automatically check out source code. You can configure or suppress this behavior with checkout.

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # if true, execute `execute git clean -ffdx && git reset --hard HEAD` before fetching
  fetchDepth: number  # the depth of commits to ask Git to fetch; defaults to no limit
  lfs: boolean  # whether to download Git-LFS files; defaults to false
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules; defaults to not checking out submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1); defaults to a directory called `s`
  persistCredentials: boolean  # if 'true', leave the OAuth token in the Git config after the initial fetch; defaults to false

Or to avoid syncing sources at all:

steps:
- checkout: none

Task

Tasks are the building blocks of a pipeline. There is a catalog of tasks available to choose from.

steps:
- task: string  # reference to a task and version, e.g. "VSBuild@1"
  displayName: string  # friendly name displayed in the UI
  name: string  # identifier for this step (A-Z, a-z, 0-9, and underscore)
  condition: string
  continueOnError: boolean  # 'true' if future steps should run even if this step fails; defaults to 'false'
  enabled: boolean  # whether or not to run this step; defaults to 'true'
  timeoutInMinutes: number
  inputs: { string: string }  # task-specific inputs
  env: { string: string }  # list of environment variables to add

Syntax highlighting

Syntax highlighting is available for the pipeline schema via a VS Code extension. You can download VS Code, install the extension, and check out the project on GitHub.

The extension includes a JSON schema for validation.