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: 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 # Stage-specific variables
jobs: [ job | deployment | template ]
Properties that use this definition: stages
Properties
stage
string
Required as first parameter. ID of the stage.displayName
string
Human-readable name for the stage.pool
dependsOn
string or string list
Any stages which must complete before this one.condition
string
Evaluate this condition expression to determine whether to run this stage.variables
jobs
stages:
- 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 ] # Any stages which must complete before this one
condition: string # Evaluate this condition expression to determine whether to run this stage.
variables: variables # Stage-specific variables
jobs: [ job | deployment | template ]
Properties that use this definition: stages
Properties
stage
string
Required as first parameter. ID of the stage.displayName
string
Human-readable name for the stage.pool
dependsOn
string or string list
Any stages which must complete before this one.condition
string
Evaluate this condition expression to determine whether to run this stage.variables
jobs
stages:
- 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 ] # Any stages which must complete before this one
condition: string # Evaluate this condition expression to determine whether to run this stage.
variables: variables # Stage-specific variables
jobs: [ job | deployment | template ]
lockBehavior: string # Behavior lock requests from this stage should exhibit in relation to other exclusive lock requests. (runLatest,sequential)
templateContext: # Stage related information passed from a pipeline when extending a template. See remarks for more information.
Properties that use this definition: stages
Properties
stage
string
Required as first parameter. ID of the stage.displayName
string
Human-readable name for the stage.pool
dependsOn
string or string list
Any stages which must complete before this one.condition
string
Evaluate this condition expression to determine whether to run this stage.variables
jobs
lockBehavior
string
Behavior lock requests from this stage should exhibit in relation to other exclusive lock requests.templateContext
templateContext
Stage related information passed from a pipeline when extending a template. See remarks for more information.stages:
- 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 ] # Any stages which must complete before this one
condition: string # Evaluate this condition expression to determine whether to run this stage.
variables: variables # Stage-specific variables
jobs: [ job | deployment | template ]
lockBehavior: string # Behavior lock requests from this stage should exhibit in relation to other exclusive lock requests. (runLatest,sequential)
templateContext: # Stage related information passed from a pipeline when extending a template. See remarks for more information.
Properties that use this definition: stages
Properties
stage
string
Required as first parameter. ID of the stage.displayName
string
Human-readable name for the stage.pool
dependsOn
string or string list
Any stages which must complete before this one.condition
string
Evaluate this condition expression to determine whether to run this stage.variables
jobs
lockBehavior
string
Behavior lock requests from this stage should exhibit in relation to other exclusive lock requests.templateContext
templateContext
Stage related information passed from a pipeline when extending a template. See remarks for more information.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 nolockBehavioris 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:
- Enable the exclusive lock check on the environment (or another protected resource).
- 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.
Feedback
Submit and view feedback for