Expressions

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020

Expressions can be used in many places where you need to specify a string, boolean, or number value when authoring a pipeline. When an expression returns an array, normal indexing rules apply and the index starts with 0.

The most common use of expressions is in conditions to determine whether a job or step should run.

An expression can be a literal, a reference to a variable, a reference to a dependency, a function, or a valid nested combination of these.

Literals

As part of an expression, you can use boolean, null, number, string, or version literals.

# Examples
variables:
  someBoolean: ${{ true }} # case insensitive, so True or TRUE also works
  someNumber: ${{ -1.2 }}
  someString: ${{ 'a b c' }}
  someVersion: ${{ 1.2.3 }}

Boolean

True and False are boolean literal expressions.

Null

Null is a special literal expression that's returned from a dictionary miss, for example (variables['noSuch']). Null can be the output of an expression but can't be called directly within an expression.

Number

Starts with '-', '.', or '0' through '9'.

String

Must be single-quoted. For example: 'this is a string'.

To express a literal single-quote, escape it with a single quote. For example: 'It''s OK if they''re using contractions.'.

You can use a pipe character (|) for multiline strings.

myKey: |
  one
  two
  three

Version

A version number with up to four segments. Must start with a number and contain two or three period (.) characters. For example: 1.2.3.4.

Variables

As part of an expression, you may access variables using one of two syntaxes:

• Index syntax: variables['MyVar']
• Property dereference syntax: variables.MyVar

In order to use property dereference syntax, the property name must:

• Start with a-Z or _
• Be followed by a-Z 0-9 or _

Depending on the execution context, different variables are available.

• If you create pipelines using YAML, then pipeline variables are available.
• If you create build pipelines using classic editor, then build variables are available.
• If you create release pipelines using classic editor, then release variables are available.

Variables are always strings. If you want to use typed values, then you should use parameters instead.

Functions

The following built-in functions can be used in expressions.

and

• Evaluates to True if all parameters are True
• Min parameters: 2. Max parameters: N
• Casts parameters to Boolean for evaluation
• Short-circuits after first False
• Example: and(eq(variables.letters, 'ABC'), eq(variables.numbers, 123))

contains

• Evaluates True if left parameter String contains right parameter
• Min parameters: 2. Max parameters: 2
• Casts parameters to String for evaluation
• Performs ordinal ignore-case comparison
• Example: contains('ABCDE', 'BCD') (returns True)

containsValue

• Evaluates True if the left parameter is an array, and any item equals the right parameter. Also evaluates True if the left parameter is an object, and the value of any property equals the right parameter.
• Min parameters: 2. Max parameters: 2
• If the left parameter is an array, convert each item to match the type of the right parameter. If the left parameter is an object, convert the value of each property to match the type of the right parameter. The equality comparison for each specific item evaluates False if the conversion fails.
• Ordinal ignore-case comparison for Strings
• Short-circuits after the first match

You can use the containsValue expression to find a matching value in an object. Here's an example that demonstrates looking in list of source branches for a match for Build.SourceBranch.

parameters:
- name: branchOptions
  displayName: Source branch options
  type: object
  default:
    - refs/heads/main
    - refs/heads/test

jobs:
  - job: A1 
    steps:
    - ${{ each value in parameters.branchOptions }}:
      - script: echo ${{ value }}

  - job: B1 
    condition: ${{ containsValue(parameters.branchOptions, variables['Build.SourceBranch']) }}
    steps:
      - script: echo "Matching branch found"

endsWith

• Evaluates True if left parameter String ends with right parameter
• Min parameters: 2. Max parameters: 2
• Casts parameters to String for evaluation
• Performs ordinal ignore-case comparison
• Example: endsWith('ABCDE', 'DE') (returns True)

eq

• Evaluates True if parameters are equal
• Min parameters: 2. Max parameters: 2
• Converts right parameter to match type of left parameter. Returns False if conversion fails.
• Ordinal ignore-case comparison for Strings
• Example: eq(variables.letters, 'ABC')

ge

• Evaluates True if left parameter is greater than or equal to the right parameter
• Min parameters: 2. Max parameters: 2
• Converts right parameter to match type of left parameter. Errors if conversion fails.
• Ordinal ignore-case comparison for Strings
• Example: ge(5, 5) (returns True)

gt

• Evaluates True if left parameter is greater than the right parameter
• Min parameters: 2. Max parameters: 2
• Converts right parameter to match type of left parameter. Errors if conversion fails.
• Ordinal ignore-case comparison for Strings
• Example: gt(5, 2) (returns True)

in

• Evaluates True if left parameter is equal to any right parameter
• Min parameters: 1. Max parameters: N
• Converts right parameters to match type of left parameter. Equality comparison evaluates False if conversion fails.
• Ordinal ignore-case comparison for Strings
• Short-circuits after first match
• Example: in('B', 'A', 'B', 'C') (returns True)

le

• Evaluates True if left parameter is less than or equal to the right parameter
• Min parameters: 2. Max parameters: 2
• Converts right parameter to match type of left parameter. Errors if conversion fails.
• Ordinal ignore-case comparison for Strings
• Example: le(2, 2) (returns True)

length

• Returns the length of a string or an array, either one that comes from the system or that comes from a parameter
• Min parameters: 1. Max parameters 1
• Example: length('fabrikam') returns 8

lt

• Evaluates True if left parameter is less than the right parameter
• Min parameters: 2. Max parameters: 2
• Converts right parameter to match type of left parameter. Errors if conversion fails.
• Ordinal ignore-case comparison for Strings
• Example: lt(2, 5) (returns True)

ne

• Evaluates True if parameters are not equal
• Min parameters: 2. Max parameters: 2
• Converts right parameter to match type of left parameter. Returns True if conversion fails.
• Ordinal ignore-case comparison for Strings
• Example: ne(1, 2) (returns True)

not

• Evaluates True if parameter is False
• Min parameters: 1. Max parameters: 1
• Converts value to Boolean for evaluation
• Example: not(eq(1, 2)) (returns True)

notIn

• Evaluates True if left parameter isn't equal to any right parameter
• Min parameters: 1. Max parameters: N
• Converts right parameters to match type of left parameter. Equality comparison evaluates False if conversion fails.
• Ordinal ignore-case comparison for Strings
• Short-circuits after first match
• Example: notIn('D', 'A', 'B', 'C') (returns True)

or

• Evaluates True if any parameter is True
• Min parameters: 2. Max parameters: N
• Casts parameters to Boolean for evaluation
• Short-circuits after first True
• Example: or(eq(1, 1), eq(2, 3)) (returns True, short-circuits)

startsWith

• Evaluates True if left parameter string starts with right parameter
• Min parameters: 2. Max parameters: 2
• Casts parameters to String for evaluation
• Performs ordinal ignore-case comparison
• Example: startsWith('ABCDE', 'AB') (returns True)

xor

• Evaluates True if exactly one parameter is True
• Min parameters: 2. Max parameters: 2
• Casts parameters to Boolean for evaluation
• Example: xor(True, False) (returns True)

Job status check functions

You can use the following status check functions as expressions in conditions, but not in variable definitions.

always

• Always evaluates to True (even when canceled). Note: A critical failure may still prevent a task from running. For example, if getting sources failed.

canceled

• Evaluates to True if the pipeline was canceled.

failed

• For a step, equivalent to eq(variables['Agent.JobStatus'], 'Failed').
• For a job:
  • With no arguments, evaluates to True only if any previous job in the dependency graph failed.
  • With job names as arguments, evaluates to True only if any of those jobs failed.

succeeded

• For a step, equivalent to in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues')
• Use with dependsOn when working with jobs and you want to evaluate whether a previous job was successful. Jobs are designed to run in parallel while stages run sequentially.
• For a job:
  • With no arguments, evaluates to True only if all previous jobs in the dependency graph succeeded or partially succeeded.
  • With job names as arguments, evaluates to True if all of those jobs succeeded or partially succeeded.
  • Evaluates to False if the pipeline is canceled.

succeededOrFailed

• For a step, equivalent to in(variables['Agent.JobStatus'], 'Succeeded', 'SucceededWithIssues', 'Failed')

• For a job:

  • With no arguments, evaluates to True regardless of whether any jobs in the dependency graph succeeded or failed.
  • With job names as arguments, evaluates to True whether any of those jobs succeeded or failed.
  • You may want to use not(canceled()) instead when there are previous skipped jobs in the dependency graph.

  This is like always(), except it will evaluate False when the pipeline is canceled.

Conditional insertion

Conditionals only work when using template syntax. Learn more about variable syntax.

For templates, you can use conditional insertion when adding a sequence or mapping. Learn more about conditional insertion in templates.

Conditionally assign a variable

variables:
  ${{ if eq(variables['Build.SourceBranchName'], 'main') }}: # only works if you have a main branch
    stageName: prod

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo ${{variables.stageName}}

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

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

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

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:
- 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

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

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

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

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

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

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:
        ...

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

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

Filtered arrays

When operating on a collection of items, you can use the * syntax to apply a filtered array. A filtered array returns all objects/elements regardless their names.

As an example, consider an array of objects named foo. We want to get an array of the values of the id property in each object in our array.

[
    { "id": 1, "a": "avalue1"},
    { "id": 2, "a": "avalue2"},
    { "id": 3, "a": "avalue3"}
]

We could do the following:

foo.*.id

This tells the system to operate on foo as a filtered array and then select the id property.

This would return:

[ 1, 2, 3 ]

Type casting

Values in an expression may be converted from one type to another as the expression gets evaluated. When an expression is evaluated, the parameters are coalesced to the relevant data type and then turned back into strings.

For example, in this YAML, the values True and False are converted to 1 and 0 when the expression is evaluated. The function lt() returns True when the left parameter is less than the right parameter.

variables:
  firstEval: $[lt(False, True)] # 0 vs. 1, True
  secondEval: $[lt(True, False)] # 1 vs. 0, False

steps:
- script: echo $(firstEval)
- script: echo $(secondEval)

When you use the eq() expression for evaluating equivalence, values are implicitly converted to numbers (false to 0 and true to 1).

variables:
  trueAsNumber: $[eq('true', true)] # 1 vs. 1, True
  falseAsNumber: $[eq('false', true)] # 0 vs. 1, False

steps:
- script: echo $(trueAsNumber)
- script: echo $(falseAsNumber)

In this next example, the values variables.emptyString and the empty string both evaluate as empty strings. The function coalesce() evaluates the parameters in order, and returns the first value that doesn't equal null or empty-string.

variables:
  coalesceLiteral: $[coalesce(variables.emptyString, '', 'literal value')]

steps:
- script: echo $(coalesceLiteral) # outputs literal value

Detailed conversion rules are listed further below.

Boolean

To number:

• False → 0
• True → 1

To string:

• False → 'False'
• True → 'True'

Null

• To Boolean: False
• To number: 0
• To string: '' (the empty string)

Number

• To Boolean: 0 → False, any other number → True
• To version: Must be greater than zero and must contain a nonzero decimal. Must be less than Int32.MaxValue (decimal component also).
• To string: Converts the number to a string with no thousands separator and no decimal separator.

String

• To Boolean: '' (the empty string) → False, any other string → True
• To null: '' (the empty string) → Null, any other string not convertible
• To number: '' (the empty string) → 0, otherwise, runs C#'s Int32.TryParse using InvariantCulture and the following rules: AllowDecimalPoint | AllowLeadingSign | AllowLeadingWhite | AllowThousands | AllowTrailingWhite. If TryParse fails, then it's not convertible.
• To version: runs C#'s Version.TryParse. Must contain Major and Minor component at minimum. If TryParse fails, then it's not convertible.

Version

• To Boolean: True
• To string: Major.Minor or Major.Minor.Build or Major.Minor.Build.Revision.

FAQ

I want to do something that isn't supported by expressions. What options do I have for extending Pipelines functionality?

You can customize your Pipeline with a script that includes an expression. For example, this snippet takes the BUILD_BUILDNUMBER variable and splits it with Bash. This script outputs two new variables, $MAJOR_RUN and $MINOR_RUN, for the major and minor run numbers. The two variables are then used to create two pipeline variables, $major and $minor with task.setvariable. These variables are available to downstream steps. To share variables across pipelines see Variable groups.

steps:
- bash: |
    MAJOR_RUN=$(echo $BUILD_BUILDNUMBER | cut -d '.' -f1)
    echo "This is the major run number: $MAJOR_RUN"
    echo "##vso[task.setvariable variable=major]$MAJOR_RUN"

    MINOR_RUN=$(echo $BUILD_BUILDNUMBER | cut -d '.' -f2)
    echo "This is the minor run number: $MINOR_RUN"
    echo "##vso[task.setvariable variable=minor]$MINOR_RUN"

- bash: echo "My pipeline variable for major run is $(major)"
- bash: echo "My pipeline variable for minor run is $(minor)"