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.

Definitions

pipeline
A pipeline is one or more stages that describe a CI/CD process. The pipeline definition contains the documentation for root level properties like name.

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

extends
Extends a pipeline using a template.

jobs
Specifies the jobs that make up the work of a stage.

jobs
Specifies the jobs that make up the work of a pipeline.

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

jobs.deployment.environment
Target environment name and optionally a resource name to record the deployment history; format: environment-name.resource-name.

jobs.deployment.strategy
Execution strategy for this deployment.

jobs.deployment.strategy.canary
Canary Deployment strategy.

jobs.deployment.strategy.rolling
Rolling Deployment strategy.

jobs.deployment.strategy.runOnce
RunOnce Deployment strategy.

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

jobs.job.container
Container resource name.

jobs.job.strategy
Execution strategy for this job.

jobs.job.uses
Any resources required by this job that are not already referenced.

jobs.template
A set of jobs defined in a template.

parameters
Specifies the runtime parameters passed to a pipeline.

parameters.parameter
Pipeline template parameters.

pool
Which pool to use for a job of the pipeline.

pool.demands
Demands (for a private pool).

pr
Pull request trigger.

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

resources.builds
List of build resources referenced by the pipeline.

resources.builds.build
A build resource used to reference artifacts from a run.

resources.containers
List of container images.

resources.containers.container
A container resource used to reference a container image.

resources.containers.container.trigger
Specify none to disable, true to trigger on all image tags, or use the full syntax as described in the following examples.

resources.packages
List of package resources.

resources.packages.package
A package resource used to reference a NuGet or npm GitHub package.

resources.pipelines
List of pipeline resources.

resources.pipelines.pipeline
A pipeline resource.

resources.pipelines.pipeline.trigger
Specify none to disable, true to include all branches, or use the full syntax as described in the following examples.

resources.pipelines.pipeline.trigger.branches
Branches to include or exclude for triggering a run.

resources.repositories
List of repository resources.

resources.repositories.repository
A repository resource is used to reference an additional repository in your pipeline.

resources.webhooks
List of webhooks.

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

resources.webhooks.webhook.filters
List of trigger filters.

resources.webhooks.webhook.filters.filter
Webhook resource trigger filter.

schedules
The schedules list specifies the scheduled triggers for the pipeline.

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

stages
Stages are a collection of related jobs.

stages.stage
A stage is a collection of related jobs.

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

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

steps.bash
Runs a script in Bash on Windows, macOS, and Linux.

steps.checkout
Configure how the pipeline checks out source code.

steps.download
Downloads artifacts associated with the current run or from another Azure Pipeline that is associated as a pipeline resource.

steps.downloadBuild
Downloads build artifacts.

steps.getPackage
Downloads a package from a package management feed in Azure Artifacts or Azure DevOps Server.

steps.powershell
Runs a script using either Windows PowerShell (on Windows) or pwsh (Linux and macOS).

steps.publish
Publishes (uploads) a file or folder as a pipeline artifact that other jobs and pipelines can consume.

steps.pwsh
Runs a script in PowerShell Core on Windows, macOS, and Linux.

steps.reviewApp
Downloads creates a resource dynamically under a deploy phase provider.

steps.script
Runs a script using cmd.exe on Windows and Bash on other platforms.

steps.task
Runs a task.

steps.template
Define a set of steps in one file and use it multiple times in another file.

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

target.settableVariables
Restrictions on which variables that can be set.

trigger
Continuous integration (push) trigger.

variables
Define variables using name/value pairs.

variables.group
Reference variables from a variable group.

variables.name
Define variables using name and full syntax.

variables.template
Define variables in a template.

Supporting definitions

Note

Supporting definitions are not intended for use directly in a pipeline. Supporting definitions are used only as part of other definitions, and are included here for reference.

deployHook
Used to run steps that deploy your application.

includeExcludeFilters
Lists of items to include or exclude.

includeExcludeStringFilters
Items to include or exclude.

mountReadOnly
Volumes to mount read-only, the default is all false.

onFailureHook
Used to run steps for rollback actions or clean-up.

onSuccessHook
Used to run steps for rollback actions or clean-up.

onSuccessOrFailureHook
Used to run steps for rollback actions or clean-up.

postRouteTrafficHook
Used to run the steps after the traffic is routed. Typically, these tasks monitor the health of the updated version for defined interval.

preDeployHook
Used to run steps that initialize resources before application deployment starts.

routeTrafficHook
Used to run steps that serve the traffic to the updated version.

workspace
Workspace options on the agent.

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.