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.

Pipeline structure

Pipelines are made of one or more jobs and may include resources and variables. Jobs are made of one or more steps plus some job-specific data. Steps can be tasks, scripts, or references to external templates. This 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 simpler pipelines, not all of these levels are required. For example, in a single-job build, you can omit the container for "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 complex keys and sets.

Pipeline

name: string  # build numbering format
resources:
  containers: [ container ]
  repositories: [ repository ]
variables: { string: string } | [ variable ]
trigger: trigger
pr: pr
jobs: [ job | templateReference ]

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

Variables

Hardcoded values can be added directly, or variable groups can be referenced.

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.

Container

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.

resources:
  containers:
  - container: string  # identifier (no spaces allowed)
    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

Repository

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 (no spaces allowed)
    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  # endpoint for a GitHub repository

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.

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.

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, 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

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.

Note that pr is valid for GitHub, not any other Git provider.

List syntax:

pr: [ string ] # list of branch names

Disable syntax:

pr: none # will disable CI builds entirely

Full syntax:

pr:
  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

Job

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

- job: string  # name of the job, no spaces allowed
  displayName: string  # friendly name to display in the UI
  dependsOn: string | [ string ]
  condition: string
  strategy:
    matrix: # matrix strategy, see below
    parallel: # parallel strategy, see below
    maxParallel: number # maximum number of agents to simultaneously run copies of this job on
  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 after the job runs
  container: string # container resource 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 ]
  steps: [ script | bash | powershell | checkout | task | stepTemplate ]

Learn more about variables. Also see the schema references for pool, server, script, bash, powershell, checkout, task, and step templates.

Note

If you have only one job, you can use single-job syntax which omits many of the keywords here.

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 } }

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.

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

Maximum Parallelism

Regardless of which strategy is chosen and how many jobs are generated, this value specifies the maximum number of agents which will run at a time for this family of jobs. It defaults to unlimited if not specified.

strategy:
  maxParallel: number

Job templates

Jobs can also be specified in a job template. Job templates are separate files which you can reference in the main pipeline definition.

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 templates.

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.

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.

- script: string  # contents of the script to run
  displayName: string  # friendly name displayed in the UI
  name: string  # identifier for this step (no spaces allowed)
  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.

- bash: string  # contents of the script to run
  displayName: string  # friendly name displayed in the UI
  name: string  # identifier for this step (no spaces allowed)
  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.

PowerShell

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

- powershell: string  # contents of the script to run
  displayName: string  # friendly name displayed in the UI
  name: string  # identifier for this step (no spaces allowed)
  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 prepend your script with:

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

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

ignoreLASTEXITCODE: boolean

Checkout

checkout informs the system how to handle checking out source code.

- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

Or to avoid syncing sources at all:

- checkout: none

Task

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

- 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 (no spaces allowed)
  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

Step template

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 | powershell | checkout | task ]

See templates for more about working with templates.