Add stages, dependencies, and conditions

You can organize pipeline jobs into stages. Stages are the major divisions in a pipeline: build this app, run these tests, and deploy to preproduction are good examples of stages. They're logical boundaries in your pipeline where you can pause the pipeline and perform various checks.

Every pipeline has at least one stage, even if you don't explicitly define it. You can also arrange stages into a dependency graph so that one stage runs before another one. A stage can have up to 256 jobs.

In the simplest case, you don't need logical boundaries in your pipeline. For those scenarios, you can directly specify the jobs in your YAML file without the stages keyword. For example, if you have a simple pipeline that builds and tests a small application without requiring separate environments or deployment steps, you can define all the jobs directly without using stages.

pool:
  vmImage: 'ubuntu-latest'

jobs:
- job: BuildAndTest
  steps:
  - script: echo "Building the application"
  - script: echo "Running tests"

This pipeline has one implicit stage and two jobs. The stages keyword isn't used because there's only one stage.

jobs:
- job: Build
  steps:
  - bash: echo "Building"

- job: Test
  steps:
  - bash: echo "Testing"

To organize your pipeline into multiple stages, use the stages keyword. This YAML defines a pipeline with two stages where each stage contains multiple jobs, and each job has specific steps to execute.

stages:
- stage: A
  displayName: "Stage A - Build and Test"
  jobs:
  - job: A1
    displayName: "Job A1 - build"
    steps:
    - script: echo "Building the application in Job A1"
      displayName: "Build step"
  - job: A2
    displayName: "Job A2 - Test"
    steps:
    - script: echo "Running tests in Job A2"
      displayName: "Test step"

- stage: B
  displayName: "Stage B - Deploy"
  jobs:
  - job: B1
    displayName: "Job B1 - Deploy to Staging"
    steps:
    - script: echo "Deploying to staging in Job B1"
      displayName: "Staging deployment step"
  - job: B2
    displayName: "Job B2 - Deploy to Production"
    steps:
    - script: echo "Deploying to production in Job B2"
      displayName: "Production deployment step"

If you specify a pool at the stage level, all jobs in that stage use that pool unless the stage is specified at the job level.

stages:
- stage: A
  pool: StageAPool
  jobs:
  - job: A1 # will run on "StageAPool" pool based on the pool defined on the stage
  - job: A2 # will run on "JobPool" pool
    pool: JobPool

When you define multiple stages in a pipeline, they run sequentially by default in the order you define them in the YAML file. The exception to this is when you add dependencies. With dependencies, stages run in the order of the dependsOn requirements.

Pipelines must contain at least one stage with no dependencies.

For more information on how to define stages, see stages in the YAML schema.

The following example stages run sequentially. If you don't use a dependsOn keyword, stages run in the order they're defined.

stages:
- stage: Build
  displayName: "Build Stage"
  jobs:
  - job: BuildJob
    steps:
    - script: echo "Building the application"
      displayName: "Build Step"

- stage: Test
  displayName: "Test Stage"
  jobs:
  - job: TestJob
    steps:
    - script: echo "Running tests"
      displayName: "Test Step"

Example stages that run in parallel:

stages:
- stage: FunctionalTest
  displayName: "Functional Test Stage"
  jobs:
  - job: FunctionalTestJob
    steps:
    - script: echo "Running functional tests"
      displayName: "Run Functional Tests"

- stage: AcceptanceTest
  displayName: "Acceptance Test Stage"
  dependsOn: [] # Runs in parallel with FunctionalTest
  jobs:
  - job: AcceptanceTestJob
    steps:
    - script: echo "Running acceptance tests"
      displayName: "Run Acceptance Tests"

Example of fan-out and fan-in behavior:

stages:
- stage: Test

- stage: DeployUS1
  dependsOn: Test    #  stage runs after Test

- stage: DeployUS2
  dependsOn: Test    # stage runs in parallel with DeployUS1, after Test

- stage: DeployEurope
  dependsOn:         # stage runs after DeployUS1 and DeployUS2
  - DeployUS1
  - DeployUS2

Example to run a stage based upon the status of running a previous stage:

stages:
- stage: A

# stage B runs if A fails
- stage: B
  condition: failed()

# stage C runs if B succeeds
- stage: C
  dependsOn:
  - A
  - B
  condition: succeeded('B')

Example of using a custom condition:

stages:
- stage: A

- stage: B
  condition: and(succeeded(), eq(variables['build.sourceBranch'], 'refs/heads/main'))

YAML pipelines don't support queuing policies. Each run of a pipeline is independent from and unaware of other runs. In other words, your two successive commits might trigger two pipelines, and both of them will execute the same sequence of stages without waiting for each other. While we work to bring queuing policies to YAML pipelines, we recommend that you use manual approvals in order to manually sequence and control the order the execution if this is of importance.

You can manually control when a stage should run using approval checks. This is commonly used to control deployments to production environments. Checks are a mechanism available to the resource owner to control if and when a stage in a pipeline can consume a resource. As an owner of a resource, such as an environment, you can define checks that must be satisfied before a stage consuming that resource can start.

Currently, manual approval checks are supported on environments. For more information, see Approvals.