stages.stage definition

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.

stages:
- stage: string # Required as first property. ID of the stage.
  displayName: string # Human-readable name for the stage.
  pool: string | pool # Pool where jobs in this stage will run unless otherwise specified.
  dependsOn: string | [ string ] # Any stages which must complete before this one.
  condition: string # Evaluate this condition expression to determine whether to run this stage.
  variables: variables | [ variable ] # Stage-specific variables.
  jobs: [ job | deployment | template ] # Jobs which make up the stage.
  lockBehavior: string # Behavior lock requests from this stage should exhibit in relation to other exclusive lock requests.
  templateContext: # Stage related information passed from a pipeline when extending a template.

Definitions that reference this definition: stages

Properties

stage string. Required as first property.
ID of the stage.

displayName string.
Human-readable name for the stage.

pool pool.
Pool where jobs in this stage will run unless otherwise specified.

dependsOn string | string list.
Any stages which must complete before this one. By default stages are run sequentially in the order defined in the pipeline. Specify dependsOn: [] for a stage if it shouldn't depend on the previous stage in the pipeline.

condition string.
Evaluate this condition expression to determine whether to run this stage.

variables variables.
Stage-specific variables.

jobs jobs.
Jobs which make up the stage.

lockBehavior string.
Behavior lock requests from this stage should exhibit in relation to other exclusive lock requests. sequential | runLatest.

templateContext templateContext.
Stage related information passed from a pipeline when extending a template. For more information about templateContext, see Extended YAML Pipelines templates can now be passed context information for stages, jobs, and deployments and Templates - Use templateContext to pass properties to templates.

Remarks

For more information about templateContext, see Extended YAML Pipelines templates can now be passed context information for stages, jobs, and deployments and Templates - Use templateContext to pass properties to templates.

Use approval checks to manually control when a stage should run. These checks are commonly used to control deployments to production environments.

Checks are a mechanism available to the resource owner. They control when a stage in a pipeline consumes a resource. As an owner of a resource like an environment, you can define checks that are required before a stage that consumes the resource can start.

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

Exclusive lock

In YAML pipelines, checks are used to control the execution of stages on protected resources. One of the common checks that you can use is an exclusive lock check. This check lets only a single run from the pipeline proceed. When multiple runs attempt to deploy to an environment at the same time, the check cancels all the old runs and permits the latest run to be deployed.

You can configure the behavior of the exclusive lock check using the lockBehavior property, which has two values:

• runLatest - Only the latest run acquires the lock to the resource. This is the default value if no lockBehavior is specified.
• sequential - All runs acquire the lock sequentially to the protected resource.

Canceling old runs is a good approach when your releases are cumulative and contain all the code changes from previous runs. However, there are some pipelines in which code changes are not cumulative. By configuring the lockBehavior property, you can choose to allow all runs to proceed and deploy sequentially to an environment, or preserve the previous behavior of canceling old runs and allowing just the latest. A value of sequential implies that all runs acquire the lock sequentially to the protected resource. A value of runLatest implies that only the latest run acquires the lock to the resource.

To use exclusive lock check with sequential deployments or runLatest, follow these steps:

1. Enable the exclusive lock check on the environment (or another protected resource).
2. In the YAML file for the pipeline, specify a new property called lockBehavior. This can be specified for the whole pipeline or for a given stage:

Set on a stage:

stages:
- stage: A
  lockBehavior: sequential
  jobs:
  - job: Job
    steps:
    - script: Hey!

Set on the pipeline:

lockBehavior: runLatest
stages:
- stage: A
  jobs:
  - job: Job
    steps:
    - script: Hey!

Examples

This example runs three stages, one after another. The middle stage runs two jobs in parallel.

stages:
- stage: Build
  jobs:
  - job: BuildJob
    steps:
    - script: echo Building!
- stage: Test
  jobs:
  - job: TestOnWindows
    steps:
    - script: echo Testing on Windows!
  - job: TestOnLinux
    steps:
    - script: echo Testing on Linux!
- stage: Deploy
  jobs:
  - job: Deploy
    steps:
    - script: echo Deploying the code!

This example runs two stages in parallel. For brevity, the jobs and steps are omitted.

stages:
- stage: BuildWin
  displayName: Build for Windows
- stage: BuildMac
  displayName: Build for Mac
  dependsOn: [] # by specifying an empty array, this stage doesn't depend on the stage before it

See also

Learn more about stages, conditions, and variables.