YAML schema reference for Azure Pipelines

The YAML schema reference for Azure Pipelines is a detailed reference for YAML pipelines that lists all supported YAML syntax and their available options.

To create a YAML pipeline, start with the pipeline definition. For more information about building YAML pipelines, see Customize your pipeline.

The YAML schema reference does not cover tasks. For more information about tasks, see the Azure Pipelines tasks index.

YAML schema definition index

A pipeline is one or more jobs that describe a CI/CD process.


The jobs list specifies the jobs that make up the work of a stage.


A job is a collection of steps run by an agent or on a server.


The matrix and parallel keywords specify mutually exclusive strategies for duplicating a job.


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


pr

A pull request trigger specifies which branches cause a pull request build to run.


Resources specifies builds, repositories, pipelines, and other resources used by the pipeline.


List of build resources referenced by the pipeline.


If you have an external CI build system that produces artifacts, you can consume artifacts with a build resource.


List of container resources referenced by the pipeline.


A container resource references a container image.


List of pipeline resources referenced by the pipeline.


If you have an Azure pipeline that produces artifacts, your pipeline can consume the artifacts by defining a pipeline resource. In Azure DevOps Server 2020 and higher, you can also enable pipeline completion triggers using a pipeline resource.


List of repository resources referenced by the pipeline.


The repository keyword lets you specify an external repository.


Steps are a linear sequence of operations that make up a job.


The bash step runs a script in Bash on Windows, macOS, and Linux.


Use checkout to configure how the pipeline checks out source code.


The download step downloads artifacts associated with the current run or from another Azure pipeline that is associated as a pipeline resource.


The downloadBuild step downloads build artifacts.


The powershell step runs a script in Windows PowerShell.


The publish keyword publishes (uploads) a file or folder as a pipeline artifact that other jobs and pipelines can consume.


The pwsh step runs a script in PowerShell Core on Windows, macOS, and Linux.


The restoreCache step restores a cache.


The saveCache step saves a cache.


The script step runs a script using cmd.exe on Windows and Bash on other platforms.


A task step runs a task.


You can define a set of steps in one file and use it multiple times in another file.


A push trigger specifies which branches cause a continuous integration build to run.


Define variables to use in your pipeline.


Reference variables from a variable group.


Define variables using the full syntax.


You can define a set of variables in one file and use it multiple times in other files.


A pipeline is one or more jobs that describe a CI/CD process.


The jobs list specifies the jobs that make up the work of a stage.


A job is a collection of steps run by an agent or on a server.


Container jobs allow you to run jobs on a container instead of the agent host.


The matrix and parallel keywords specify mutually exclusive strategies for duplicating a job.


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


pr

A pull request trigger specifies which branches cause a pull request build to run.


Resources specifies builds, repositories, pipelines, and other resources used by the pipeline.


List of build resources referenced by the pipeline.


If you have an external CI build system that produces artifacts, you can consume artifacts with a build resource.


List of container resources referenced by the pipeline.


A container resource references a container image.


List of pipeline resources referenced by the pipeline.


If you have an Azure pipeline that produces artifacts, your pipeline can consume the artifacts by defining a pipeline resource. In Azure DevOps Server 2020 and higher, you can also enable pipeline completion triggers using a pipeline resource.


List of repository resources referenced by the pipeline.


The repository keyword lets you specify an external repository.


Steps are a linear sequence of operations that make up a job.


The bash step runs a script in Bash on Windows, macOS, and Linux.


Use checkout to configure how the pipeline checks out source code.


The download step downloads artifacts associated with the current run or from another Azure pipeline that is associated as a pipeline resource.


The downloadBuild step downloads build artifacts.


The powershell step runs a script in Windows PowerShell.


The publish keyword publishes (uploads) a file or folder as a pipeline artifact that other jobs and pipelines can consume.


The pwsh step runs a script in PowerShell Core on Windows, macOS, and Linux.


The restoreCache step restores a cache.


The saveCache step saves a cache.


The script step runs a script using cmd.exe on Windows and Bash on other platforms.


A task step runs a task.


You can define a set of steps in one file and use it multiple times in another file.


A push trigger specifies which branches cause a continuous integration build to run.


Define variables to use in your pipeline.


Reference variables from a variable group.


Define variables using the full syntax.


You can define a set of variables in one file and use it multiple times in other files.


A pipeline is one or more stages that describe a CI/CD process.


Extends a pipeline using a template.


The jobs list specifies the jobs that make up the work of a stage.


A deployment job is a special type of job. It's a collection of steps to run sequentially against the environment.


The environment keyword specifies the environment or its resource that is targeted by a deployment job of the pipeline.


A deployment strategy enables you to configure how the update is delivered.


Canary deployment strategy rolls out changes to a small subset of servers.


A rolling deployment replaces instances of the previous version of an application with instances of the new version of the application on a fixed set of virtual machines (rolling set) in each iteration.


The runOnce deployment strategy rolls out changes by executing each of its steps one time.


A job is a collection of steps run by an agent or on a server.


Container jobs allow you to run jobs on a container instead of the agent host.


The matrix and parallel keywords specify mutually exclusive strategies for duplicating a job.


You can define a set of jobs in one file and use it multiple times in other files. See templates for more about working with job templates.


The parameters list specifies the runtime parameters passed to a pipeline.


A parameter represents a value passed to a pipeline.


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


pr

A pull request trigger specifies which branches cause a pull request build to run.


Resources specifies builds, repositories, pipelines, and other resources used by the pipeline.


List of build resources referenced by the pipeline.


If you have an external CI build system that produces artifacts, you can consume artifacts with a build resource.


List of container resources referenced by the pipeline.


A container resource references a container image.


List of package resources referenced by the pipeline.


You can consume NuGet and npm GitHub packages as a resource in YAML pipelines. When specifying package resources, set the package as NuGet or npm.


List of pipeline resources referenced by the pipeline.


If you have an Azure pipeline that produces artifacts, your pipeline can consume the artifacts by defining a pipeline resource. In Azure DevOps Server 2020 and higher, you can also enable pipeline completion triggers using a pipeline resource.


List of repository resources referenced by the pipeline.


The repository keyword lets you specify an external repository.


The schedules list specifies the scheduled triggers for the pipeline.


A scheduled trigger specifies a schedule on which branches are built.


Stages are a collection of related jobs.


Stages are a collection of related jobs. By default, stages run sequentially. Each stage starts only after the preceding stage is complete unless otherwise specified via the dependsOn property.


You can define a set of stages in one file and use it multiple times in other files.


Steps are a linear sequence of operations that make up a job.


The bash step runs a script in Bash on Windows, macOS, and Linux.


Use checkout to configure how the pipeline checks out source code.


The download step downloads artifacts associated with the current run or from another Azure pipeline that is associated as a pipeline resource.


The downloadBuild step downloads build artifacts.


The getPackage step downloads a package from a package management feed in Azure Artifacts or Azure DevOps Server.


The powershell step runs a script in Windows PowerShell.


The publish keyword publishes (uploads) a file or folder as a pipeline artifact that other jobs and pipelines can consume.


The pwsh step runs a script in PowerShell Core on Windows, macOS, and Linux.


The restoreCache step restores a cache.


The reviewApp step downloads creates a resource dynamically under a deploy phase provider.


The saveCache step saves a cache.


The script step runs a script using cmd.exe on Windows and Bash on other platforms.


A task step runs a task.


You can define a set of steps in one file and use it multiple times in another file.


Tasks run in an execution context, which is either the agent host or a container.


A push trigger specifies which branches cause a continuous integration build to run.


Define variables to use in your pipeline.


Reference variables from a variable group.


Define variables using the full syntax.


You can define a set of variables in one file and use it multiple times in other files.


A pipeline is one or more stages that describe a CI/CD process.


Extends a pipeline using a template.


The jobs list specifies the jobs that make up the work of a stage.


A deployment job is a special type of job. It's a collection of steps to run sequentially against the environment.


The environment keyword specifies the environment or its resource that is targeted by a deployment job of the pipeline.


A deployment strategy enables you to configure how the update is delivered.


Canary deployment strategy rolls out changes to a small subset of servers.


A rolling deployment replaces instances of the previous version of an application with instances of the new version of the application on a fixed set of virtual machines (rolling set) in each iteration.


The runOnce deployment strategy rolls out changes by executing each of its steps one time.


A job is a collection of steps run by an agent or on a server.


Container jobs allow you to run jobs on a container instead of the agent host.


The matrix and parallel keywords specify mutually exclusive strategies for duplicating a job.


You can define a set of jobs in one file and use it multiple times in other files. See templates for more about working with job templates.


The parameters list specifies the runtime parameters passed to a pipeline.


A parameter represents a value passed to a pipeline.


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


pr

A pull request trigger specifies which branches cause a pull request build to run.


Resources specifies builds, repositories, pipelines, and other resources used by the pipeline.


List of build resources referenced by the pipeline.


If you have an external CI build system that produces artifacts, you can consume artifacts with a build resource.


List of container resources referenced by the pipeline.


A container resource references a container image.


List of package resources referenced by the pipeline.


You can consume NuGet and npm GitHub packages as a resource in YAML pipelines. When specifying package resources, set the package as NuGet or npm.


List of pipeline resources referenced by the pipeline.


If you have an Azure pipeline that produces artifacts, your pipeline can consume the artifacts by defining a pipeline resource. In Azure DevOps Server 2020 and higher, you can also enable pipeline completion triggers using a pipeline resource.


List of repository resources referenced by the pipeline.


The repository keyword lets you specify an external repository.


List of webhook resources referenced by the pipeline.


A webhook resource enables you to integrate your pipeline with an external service to automate the workflow.


Filters used to customize the triggers for a webhook event.


A webhook filter is used to customize the triggers for a webhook event.


The schedules list specifies the scheduled triggers for the pipeline.


A scheduled trigger specifies a schedule on which branches are built.


Stages are a collection of related jobs.


Stages are a collection of related jobs. By default, stages run sequentially. Each stage starts only after the preceding stage is complete unless otherwise specified via the dependsOn property.


You can define a set of stages in one file and use it multiple times in other files.


Steps are a linear sequence of operations that make up a job.


The bash step runs a script in Bash on Windows, macOS, and Linux.


Use checkout to configure how the pipeline checks out source code.


The download step downloads artifacts associated with the current run or from another Azure pipeline that is associated as a pipeline resource.


The downloadBuild step downloads build artifacts.


The getPackage step downloads a package from a package management feed in Azure Artifacts or Azure DevOps Server.


The powershell step runs a script in Windows PowerShell.


The publish keyword publishes (uploads) a file or folder as a pipeline artifact that other jobs and pipelines can consume.


The pwsh step runs a script in PowerShell Core on Windows, macOS, and Linux.


The restoreCache step restores a cache.


The reviewApp step downloads creates a resource dynamically under a deploy phase provider.


The saveCache step saves a cache.


The script step runs a script using cmd.exe on Windows and Bash on other platforms.


A task step runs a task.


You can define a set of steps in one file and use it multiple times in another file.


Tasks run in an execution context, which is either the agent host or a container.


A push trigger specifies which branches cause a continuous integration build to run.


Define variables to use in your pipeline.


Reference variables from a variable group.


Define variables using the full syntax.


You can define a set of variables in one file and use it multiple times in other files.


A pipeline is one or more stages that describe a CI/CD process.


Extends a pipeline using a template.


The jobs list specifies the jobs that make up the work of a stage.


A deployment job is a special type of job. It's a collection of steps to run sequentially against the environment.


The environment keyword specifies the environment or its resource that is targeted by a deployment job of the pipeline.


A deployment strategy enables you to configure how the update is delivered.


Canary deployment strategy rolls out changes to a small subset of servers.


A rolling deployment replaces instances of the previous version of an application with instances of the new version of the application on a fixed set of virtual machines (rolling set) in each iteration.


The runOnce deployment strategy rolls out changes by executing each of its steps one time.


A job is a collection of steps run by an agent or on a server.


Container jobs allow you to run jobs on a container instead of the agent host.


The matrix and parallel keywords specify mutually exclusive strategies for duplicating a job.


You can define a set of jobs in one file and use it multiple times in other files. See templates for more about working with job templates.


The parameters list specifies the runtime parameters passed to a pipeline.


A parameter represents a value passed to a pipeline.


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


pr

A pull request trigger specifies which branches cause a pull request build to run.


Resources specifies builds, repositories, pipelines, and other resources used by the pipeline.


List of build resources referenced by the pipeline.


If you have an external CI build system that produces artifacts, you can consume artifacts with a build resource.


List of container resources referenced by the pipeline.


A container resource references a container image.


List of package resources referenced by the pipeline.


You can consume NuGet and npm GitHub packages as a resource in YAML pipelines. When specifying package resources, set the package as NuGet or npm.


List of pipeline resources referenced by the pipeline.


If you have an Azure pipeline that produces artifacts, your pipeline can consume the artifacts by defining a pipeline resource. In Azure DevOps Server 2020 and higher, you can also enable pipeline completion triggers using a pipeline resource.


List of repository resources referenced by the pipeline.


The repository keyword lets you specify an external repository.


List of webhook resources referenced by the pipeline.


A webhook resource enables you to integrate your pipeline with an external service to automate the workflow.


Filters used to customize the triggers for a webhook event.


A webhook filter is used to customize the triggers for a webhook event.


The schedules list specifies the scheduled triggers for the pipeline.


A scheduled trigger specifies a schedule on which branches are built.


Stages are a collection of related jobs.


Stages are a collection of related jobs. By default, stages run sequentially. Each stage starts only after the preceding stage is complete unless otherwise specified via the dependsOn property.


You can define a set of stages in one file and use it multiple times in other files.


Steps are a linear sequence of operations that make up a job.


The bash step runs a script in Bash on Windows, macOS, and Linux.


Use checkout to configure how the pipeline checks out source code.


The download step downloads artifacts associated with the current run or from another Azure pipeline that is associated as a pipeline resource.


The downloadBuild step downloads build artifacts.


The getPackage step downloads a package from a package management feed in Azure Artifacts or Azure DevOps Server.


The powershell step runs a script in Windows PowerShell.


The publish keyword publishes (uploads) a file or folder as a pipeline artifact that other jobs and pipelines can consume.


The pwsh step runs a script in PowerShell Core on Windows, macOS, and Linux.


The restoreCache step restores a cache.


The reviewApp step downloads creates a resource dynamically under a deploy phase provider.


The saveCache step saves a cache.


The script step runs a script using cmd.exe on Windows and Bash on other platforms.


A task step runs a task.


You can define a set of steps in one file and use it multiple times in another file.


Tasks run in an execution context, which is either the agent host or a container.


Variables that can be set by a step.


A push trigger specifies which branches cause a continuous integration build to run.


Define variables to use in your pipeline.


Reference variables from a variable group.


Define variables using the full syntax.


You can define a set of variables in one file and use it multiple times in other files.


YAML schema documentation conventions

The YAML schema reference is a detailed reference guide to Azure Pipelines YAML pipelines. It includes a catalog of all supported YAML capabilities and the available options.

Here are the syntax conventions used in the YAML schema reference.

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

See also

This reference covers the schema of an Azure Pipelines YAML file. To learn the basics of YAML, see Learn YAML in Y Minutes. Azure Pipelines doesn't support all YAML features. Unsupported features include anchors, complex keys, and sets. Also, unlike standard YAML, Azure Pipelines depends on seeing stage, job, task, or a task shortcut like script as the first key in a mapping.