Expressions

# Expressions are used to define conditions for a step, job, or stage
steps:
- task: ...
  condition: <expression>

Another common use of expressions is in defining variables. Expressions can be evaluated at compile time or at run time. Compile time expressions can be used anywhere; runtime expressions can be used in variables and conditions. Runtime expressions are intended as a way to compute the contents of variables and state (example: condition).

# Two examples of expressions used to define variables
# The first one, a, is evaluated when the YAML file is compiled into a plan.
# The second one, b, is evaluated at runtime.
# Note the syntax ${{}} for compile time and $[] for runtime expressions.
variables:
  a: ${{ <expression> }}
  b: $[ <expression> ]

The difference between runtime and compile time expression syntaxes is primarily what context is available. In a compile-time expression (${{ <expression> }}), you have access to parameters and statically defined variables. In a runtime expression ($[ <expression> ]), you have access to more variables but no parameters.

In this example, a runtime expression sets the value of $(isMain). A static variable in a compile expression sets the value of $(compileVar).

variables:
  staticVar: 'my value' # static variable
  compileVar: ${{ variables.staticVar }} # compile time expression
  isMain: $[eq(variables['Build.SourceBranch'], 'refs/heads/main')] # runtime expression

steps:
  - script: |
      echo ${{variables.staticVar}} # outputs my value
      echo $(compileVar) # outputs my value
      echo $(isMain) # outputs True

coalesce

• Evaluates the parameters in order (left to right), and returns the first value that does not equal null or empty-string.
• No value is returned if the parameter values all are null or empty strings.
• Min parameters: 2. Max parameters: N
• Example: coalesce(variables.couldBeNull, variables.couldAlsoBeNull, 'literal so it always works')

convertToJson

• Take a complex object and outputs it as JSON.
• Min parameters: 1. Max parameters: 1.

parameters:
  - name: listOfValues
    type: object
    default:
      this_is:
        a_complex: object
        with:
          - one
          - two

steps:
- script: |
    echo "${MY_JSON}"
  env:
    MY_JSON: ${{ convertToJson(parameters.listOfValues) }}

Script output:

{
  "this_is": {
    "a_complex": "object",
    "with": [
      "one",
      "two"
    ]
  }
}

counter

• This function can only be used in an expression that defines a variable. It cannot be used as part of a condition for a step, job, or stage.
• Evaluates a number that is incremented with each run of a pipeline.
• Parameters: 2. prefix and seed.
• Prefix is a string expression. A separate value of counter is tracked for each unique value of prefix. The prefix should use UTF-16 characters.
• Seed is the starting value of the counter

You can create a counter that is automatically incremented by one in each execution of your pipeline. When you define a counter, you provide a prefix and a seed. Here is an example that demonstrates this.

variables:
  major: 1
  # define minor as a counter with the prefix as variable major, and seed as 100.
  minor: $[counter(variables['major'], 100)]

steps:
- bash: echo $(minor)

The value of minor in the above example in the first run of the pipeline will be 100. In the second run it will be 101, provided the value of major is still 1.

If you edit the YAML file, and update the value of the variable major to be 2, then in the next run of the pipeline, the value of minor will be 100. Subsequent runs will increment the counter to 101, 102, 103, ...

Later, if you edit the YAML file, and set the value of major back to 1, then the value of the counter resumes where it left off for that prefix. In this example, it resumes at 102.

Here is another example of setting a variable to act as a counter that starts at 100, gets incremented by 1 for every run, and gets reset to 100 every day.

jobs:
- job:
  variables:
    a: $[counter(format('{0:yyyyMMdd}', pipeline.startTime), 100)]
  steps:
  - bash: echo $(a)

Here is an example of having a counter that maintains a separate value for PRs and CI runs.

variables:
  patch: $[counter(variables['build.reason'], 0)]

Counters are scoped to a pipeline. In other words, its value is incremented for each run of that pipeline. There are no project-scoped counters.

format

• Evaluates the trailing parameters and inserts them into the leading parameter string
• Min parameters: 1. Max parameters: N
• Example: format('Hello {0} {1}', 'John', 'Doe')
• Uses .NET custom date and time format specifiers for date formatting (yyyy, yy, MM, M, dd, d, HH, H, m, mm, ss, s, f, ff, ffff, K)
• Example: format('{0:yyyyMMdd}', pipeline.startTime). In this case pipeline.startTime is a special date time object variable.
• Escape by doubling braces. For example: format('literal left brace {{ and literal right brace }}')

join

• Concatenates all elements in the right parameter array, separated by the left parameter string.
• Min parameters: 2. Max parameters: 2
• Each element in the array is converted to a string. Complex objects are converted to empty string.
• If the right parameter is not an array, the result is the right parameter converted to a string.

In this example, a semicolon gets added between each item in the array. The parameter type is an object.

parameters:
- name: myArray
  type: object
  default:
    - FOO
    - BAR
    - ZOO

variables:
   A: ${{ join(';',parameters.myArray) }}

steps:
  - script: echo $A # outputs FOO;BAR;ZOO

lower

• Converts a string or variable value to all lowercase characters
• Min parameters: 1. Max parameters 1
• Returns the lowercase equivalent of a string
• Example: lower('FOO') returns foo

replace

• Returns a new string in which all instances of a string in the current instance are replaced with another string
• Min parameters: 3. Max parameters: 3
• replace(a, b, c): returns a, with all instances of b replaced by c
• Example: replace('https://www.tinfoilsecurity.com/saml/consume','https://www.tinfoilsecurity.com','http://server') (returns http://server/saml/consume)

split

• Splits a string into substrings based on the specified delimiting characters
• Min parameters: 2. Max parameters: 2
• The first parameter is the string to split
• The second parameter is the delimiting characters
• Returns an array of substrings. The array includes empty strings when the delimiting characters appear consecutively or at the end of the string
• Example:

  variables:
  - name: environments
    value: prod1,prod2 
  steps:  
    - ${{ each env in split(variables.environments, ',')}}:
      - script: ./deploy.sh --environment ${{ env }}
  

• Example of using split() with replace():

  parameters:
  - name: resourceIds
    type: object
    default:
    - /subscriptions/mysubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/loadBalancers/kubernetes-internal
    - /subscriptions/mysubscription02/resourceGroups/myResourceGroup02/providers/Microsoft.Network/loadBalancers/kubernetes
  - name: environments
    type: object
    default: 
    - prod1
    - prod2
  
  trigger:
  - main
  
  steps:
  - ${{ each env in parameters.environments }}:
    - ${{ each resourceId in parameters.resourceIds }}:
        - script: echo ${{ replace(split(resourceId, '/')[8], '-', '_') }}_${{ env }}
  

upper

• Converts a string or variable value to all uppercase characters
• Min parameters: 1. Max parameters 1
• Returns the uppercase equivalent of a string
• Example: upper('bah') returns BAH

You can use if, elseif, and else clauses to conditionally assign variable values or set inputs for tasks. You can also conditionally run a step when a condition is met.

You can use if to conditionally assign variable values or set inputs for tasks. You can also conditionally run a step when a condition is met.

The elseif and else clauses are available starting with Azure DevOps 2022 and are not available for Azure DevOps Server 2020 and earlier versions of Azure DevOps.

Conditionally set a task input

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: PublishPipelineArtifact@1
  inputs:
    targetPath: '$(Pipeline.Workspace)'
    ${{ if eq(variables['Build.SourceBranchName'], 'main') }}:
      artifact: 'prod'
    ${{ else }}:
      artifact: 'dev'
    publishLocation: 'pipeline'

Conditionally run a step

If there is no variable set, or the value of foo does not match the if conditions, the else statement will run. Here the value of foo returns true in the elseif condition.

variables:
  - name: foo
    value: contoso # triggers elseif condition

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo "start"
- ${{ if eq(variables.foo, 'adaptum') }}:
  - script: echo "this is adaptum"
- ${{ elseif eq(variables.foo, 'contoso') }}: # true
  - script: echo "this is contoso" 
- ${{ else }}:
  - script: echo "the value is not adaptum or contoso"

Each keyword

You can use the each keyword to loop through parameters with the object type.

parameters:
- name: listOfStrings
  type: object
  default:
  - one
  - two

steps:
- ${{ each value in parameters.listOfStrings }}:
  - script: echo ${{ value }}

Additionally, you can iterate through nested elements within an object.

parameters:
- name: listOfFruits
  type: object
  default:
  - fruitName: 'apple'
    colors: ['red','green']
  - fruitName: 'lemon'
    colors: ['yellow']
steps:
- ${{ each fruit in parameters.listOfFruits }} :
  - ${{ each fruitColor in fruit.colors}} :
    - script: echo ${{ fruit.fruitName}} ${{ fruitColor }}

Dependencies

Expressions can use the dependencies context to reference previous jobs or stages. You can use dependencies to:

• Reference the job status of a previous job
• Reference the stage status of a previous stage
• Reference output variables in the previous job in the same stage
• Reference output variables in the previous stage in a stage
• Reference output variables in a job in a previous stage in the following stage

The context is called dependencies for jobs and stages and works much like variables. If you refer to an output variable from a job in another stage, the context is called stageDependencies.

If you experience issues with output variables having quote characters (' or ") in them, see this troubleshooting guide.

Dependency syntax overview

The syntax of referencing output variables with dependencies varies depending on the circumstances. Here's an overview of the most common scenarios. Note that there may be times when alternate syntax also works.

There are also different syntaxes for output variables in deployment jobs depending on the deployment strategy. For more information, see Deployment jobs.

Stage to stage dependencies

Structurally, the dependencies object is a map of job and stage names to results and outputs. Expressed as JSON, it would look like:

"dependencies": {
  "<STAGE_NAME>" : {
    "result": "Succeeded|SucceededWithIssues|Skipped|Failed|Canceled",
    "outputs": {
        "jobName.stepName.variableName": "value"
    }
  },
  "...": {
    // another stage
  }
}

Use this form of dependencies to map in variables or check conditions at a stage level.

In this example, there are two stages, A and B. Stage A has the condition false and won't ever run as a result. Stage B runs if the result of Stage A is Succeeded, SucceededWithIssues, or Skipped. Stage B will run because Stage A was skipped.

stages:
- stage: A
  condition: false
  jobs:
  - job: A1
    steps:
    - script: echo Job A1
- stage: B
  condition: in(dependencies.A.result, 'Succeeded', 'SucceededWithIssues', 'Skipped')
  jobs:
  - job: B1
    steps:
    - script: echo Job B1

Stages can also use output variables from another stage. In this example, there are also two stages. Stage A includes a job, A1, that sets an output variable shouldrun to true. Stage B runs when shouldrun is true. Because shouldrun is true, Stage B runs.

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - bash: echo "##vso[task.setvariable variable=shouldrun;isOutput=true]true"
     # or on Windows:
     # - script: echo ##vso[task.setvariable variable=shouldrun;isOutput=true]true
       name: printvar

- stage: B
  condition: and(succeeded(), eq(dependencies.A.outputs['A1.printvar.shouldrun'], 'true'))
  dependsOn: A
  jobs:
  - job: B1
    steps:
    - script: echo hello from Stage B

Job to job dependencies within one stage

At the job level within a single stage, the dependencies data doesn't contain stage-level information.

"dependencies": {
  "<JOB_NAME>": {
    "result": "Succeeded|SucceededWithIssues|Skipped|Failed|Canceled",
    "outputs": {
      "stepName.variableName": "value1"
    }
  },
  "...": {
    // another job
  }
}

In this example, there are three jobs (a, b, and c). Job a will always be skipped because of condition: false. Job b runs because there are no associated conditions. Job c runs because all of its dependencies either succeed (job b) or are skipped (job a).

jobs:
- job: a
  condition: false
  steps:
  - script: echo Job a
- job: b
  steps:
  - script: echo Job b
- job: c
  dependsOn:
  - a
  - b
  condition: |
    and
    (
      in(dependencies.a.result, 'Succeeded', 'SucceededWithIssues', 'Skipped'),
      in(dependencies.b.result, 'Succeeded', 'SucceededWithIssues', 'Skipped')
    )
  steps:
  - script: echo Job c

In this example, Job B depends on an output variable from Job A.

jobs:
- job: A
  steps:
  - bash: echo "##vso[task.setvariable variable=shouldrun;isOutput=true]true"
  # or on Windows:
  # - script: echo ##vso[task.setvariable variable=shouldrun;isOutput=true]true
    name: printvar

- job: B
  condition: and(succeeded(), eq(dependencies.A.outputs['printvar.shouldrun'], 'true'))
  dependsOn: A
  steps:
  - script: echo hello from B

Job to job dependencies across stages

At the job level, you can also reference outputs from a job in a previous stage. This requires using the stageDependencies context.

"stageDependencies": {
  "<STAGE_NAME>" : {
    "<JOB_NAME>": {
      "result": "Succeeded|SucceededWithIssues|Skipped|Failed|Canceled",
      "outputs": {
          "stepName.variableName": "value"
      }
    },
    "...": {
      // another job
    }
  },
  "...": {
    // another stage
  }
}

In this example, job B1 will run if job A1 is skipped. Job B2 will check the value of the output variable from job A1 to determine whether it should run.

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - bash: echo "##vso[task.setvariable variable=shouldrun;isOutput=true]true"
     # or on Windows:
     # - script: echo ##vso[task.setvariable variable=shouldrun;isOutput=true]true
       name: printvar

- stage: B
  dependsOn: A
  jobs:
  - job: B1
    condition: in(stageDependencies.A.A1.result, 'Skipped') # change condition to `Succeeded and stage will be skipped`
    steps:
    - script: echo hello from Job B1
  - job: B2
    condition: eq(stageDependencies.A.A1.outputs['printvar.shouldrun'], 'true')
    steps:
     - script: echo hello from Job B2

If a job depends on a variable defined by a deployment job in a different stage, then the syntax is different. In the following example, the job run_tests runs if the build_job deployment job set runTests to true. Notice that the key used for the outputs dictionary is build_job.setRunTests.runTests.

stages:
- stage: build
  jobs:
  - deployment: build_job
    environment:
      name: Production
    strategy:
      runOnce:
        deploy:
          steps:
          - task: PowerShell@2
            name: setRunTests
            inputs:
              targetType: inline
              pwsh: true
              script: |
                $runTests = "true"
                echo "setting runTests: $runTests"
                echo "##vso[task.setvariable variable=runTests;isOutput=true]$runTests"

- stage: test
  dependsOn:
  - 'build'
  jobs:  
    - job: run_tests
      condition: eq(stageDependencies.build.build_job.outputs['build_job.setRunTests.runTests'], 'true')
      steps:
        ...

Deployment job output variables

If a stage depends on a variable defined by a deployment job in a different stage, then the syntax is different. In the following example, the stage test depends on the deployment build_job setting shouldTest to true. Notice that in the condition of the test stage, build_job appears twice.

stages:
- stage: build
  jobs:
  - deployment: build_job
    environment:
      name: Production
    strategy:
      runOnce:
        deploy:
          steps:
          - task: PowerShell@2
            name: setRunTests
            inputs:
              targetType: inline
              pwsh: true
              script: |
                $runTests = "true"
                echo "setting runTests: $runTests"
                echo "##vso[task.setvariable variable=runTests;isOutput=true]$runTests"

- stage: test
  dependsOn:
  - 'build'
  condition: eq(dependencies.build.outputs['build_job.build_job.setRunTests.runTests'], 'true')
  jobs:
    - job: A
      steps:
        - script: echo Hello from job A

In the example above, the condition references an environment and not an environment resource. To reference an environment resource, you'll need to add the environment resource name to the dependencies condition. In the following example, condition references an environment virtual machine resource named vmtest.

stages:
- stage: build
  jobs:
  - deployment: build_job
    environment:
      name: vmtest
      resourceName: winVM2
      resourceType: VirtualMachine
    strategy:
      runOnce:
        deploy:
          steps:
          - task: PowerShell@2
            name: setRunTests
            inputs:
              targetType: inline
              pwsh: true
              script: |
                $runTests = "true"
                echo "setting runTests: $runTests"
                echo "##vso[task.setvariable variable=runTests;isOutput=true]$runTests"

- stage: test
  dependsOn:
  - 'build'
  condition: eq(dependencies.build.outputs['build_job.Deploy_winVM2.setRunTests.runTests'], 'true')
  jobs:
  - job: A
    steps:
     - script: echo Hello from job A