Skip to content

Expressions

You can evaluate expressions in workflows and hooks.

About expressions

You can use expressions to programmatically set variables in workflow files and access contexts. An expression can be any combination of literal values, references to a context, or functions. You can combine literals, context references, and functions using operators. For more information about contexts, see “Contexts.”

Expressions are commonly used with the conditional if keyword in a workflow file to determine whether a step should run. When an if conditional is true, the step will run.

You need to use specific syntax to tell the OpenTestFactory orchestrator to evaluate an expression rather than treat it as a string.

${{ <expression> }}

When you use expressions in an if conditional, you may omit the expression syntax (${{ }}) because the orchestrator automatically evaluates the if conditional as an expression. However, this rule does not apply everywhere.

You must use the ${{ }} expression syntax or escape with '', "", or () when the expression starts with !, since ! is reserved notation in YAML format.

Using the ${{ }} expression syntax turns the contents into a string, and strings are truthy. For example, if: true && ${{ false }} will evaluate to true. For more information about if conditionals, see “Workflow syntax for OpenTestFactory orchestrator.”

Warning

When creating workflows and provider tasks, you should always consider whether your code might execute untrusted input from possible attackers. Certain contexts should be treated as untrusted input, as an attacker could insert their own malicious content. For more information, see “Understanding the risk of script injections.”

Example expression in an if conditional

steps:
  - run: dir /s
    if: runner.os == 'windows'  # or: ${{ runner.os == 'windows' }}

Example setting an environment variable

variables:
  my_env_var: ${{ <expression> }}

Literals

As part of an expression, you can use boolean, null, number, or string data types. Boolean literals are not case-sensitive, so you can use true or True.

Data type Literal value
boolean true or false
null null
number Any number format supported by JSON.
string You must use single quotes. Escape literal single-quotes with a single quote.

Example

variables:
  myNull: ${{ null }}
  myBoolean: ${{ false }}
  myIntegerNumber: ${{ 711 }}
  myFloatNumber: ${{ -9.2 }}
  myHexNumber: ${{ 0xff }}
  myExponentialNumber: ${{ -2.99-e2 }}
  myString: ${{ 'Mona the Octocat' }}
  myEscapedString: ${{ 'It''s open source!' }}

Operators

Operator Description Usage
( ) Logical grouping ((foo == 4) || (bar == 5)) && (baz == 6)
[ ] Index variables['VAR']
. Property dereference variables.VAR
! Not !failure()
< Less than 12 < 4
<= Less than or equal 12 <= 4
> Greater than 12 > 4
>= Greater than or equal 12 >= 4
== Equal variables.VAR == 'foo'
!= Not equal 12 != 4
~= Match regular expression variables.VAR ~= '^abc.*'
&& And true && false
|| Or true || false

The orchestrator performs loose equality comparisons.

  • If the types do not match, the orchestrator coerces the type to a number. The orchestrator casts data types to a number using these conversions:

    Type Result
    Null 0
    Boolean true returns 1
    false returns 0
    String Parsed from any legal JSON number format, otherwise NaN.
    Note: empty string returns 0.
    Array NaN
    Object NaN
  • A comparison of one NaN to another NaN does not result in true. For more information, see the “NaN Mozilla docs.”

  • The orchestrator ignores the case when comparing strings.

  • For more information on the regular expression syntax, see “Python re module.”

  • Objects and arrays are only considered equal when they are the same instance.

  • Expression evaluation is left-associative, and comparison operators have precedence over logical operators. foo == 4 || bar == 5 is evaluated as (foo == 4) || (bar == 5).

Ternary operator-like behavior

The orchestrator offers ternary operator-like behavior that you can use in expressions. By using a ternary operator in this way, you can dynamically set the value of an environment variable based on a condition, without having to write separate if-else blocks for each possible option.

Example

variables:
  MY_ENV_VAR: ${{ variables.GIT_REF == 'refs/heads/main' && 'value_for_main_branch' || 'value_for_other_branches' }}

In this example, we’re using a ternary operator to set the value of the MY_ENV_VAR environment variable based on whether the Git reference is set to refs/heads/main or not. If it is, the variable is set to value_for_main_branch. Otherwise, it is set to value_for_other_branches. It is important to note that the first value after the && condition must be truthy otherwise the value after the || will always be returned.

Functions

The orchestrator offers a set of built-in functions that you can use in expressions. Some functions cast values to a string to perform comparisons. The orchestrator casts data types to a string using these conversions:

Type Result
Null ’‘
Boolean ‘true’ or ‘false’
Number Decimal format, exponential for large numbers
Array Arrays are not converted to a string
Object Objects are not converted to a string

contains

contains( search, item )

Returns true if search contains item. If search is an array or an object, this function returns true if the item is an element in the array. If search is a string, this function returns true if the item is a substring of search. This function is not case-sensitive. Casts values to a string.

Example using a string

contains('Hello world', 'llo') returns true.

Example using an object

contains(variables, 'bug') returns true if a variable “bug” exists.

Example matching an array of strings

Instead of writing variables.event_name == 'push' || variables.event_name == 'pull_request', you can use contains() with fromJSON() to check if an array of strings contains an item.

For example, contains(fromJSON('["push", "pull_request"]'), variables.event_name) returns true if variables.event_name is “push” or “pull_request”.

toJSON

toJSON( value )

Returns a pretty-print JSON representation of value. You can use this function to debug the information provided in contexts.

Example of toJSON

toJSON(job) might return { "status": "success" }.

fromJSON

fromJSON( value )

Returns a JSON object or JSON data type for value. You can use this function to provide a JSON object as an evaluated expression or to convert environment variables from a string.

Example returning a JSON data type

This workflow uses fromJSON to convert environment variables from a string to a Boolean or integer.

variables:
  continue: true
  time: 3
jobs:
  job1:
    runs-on: linux
    steps:
      - continue-on-error: ${{ fromJSON(variables.continue) }}
        timeout-minutes: ${{ fromJSON(variables.time) }}
        run: echo ...

startsWith

startsWith( searchString, searchValue )

Returns true when searchString starts with searchValue. This function is not case-sensitive. Casts values to a string.

Example of startsWith

startsWith('Hello world', 'He') returns true.

endsWith

endsWith( searchString, searchValue )

Returns true if searchString ends with searchValue. This function is not case-sensitive. Casts values to a string.

Example of endsWith

endsWith('Hello world', 'ld') returns true.

Date functions

Timestamps are strings that follow the ISO 8601 standard.

2011-11-04
20111104
2011-11-04T00:05:23
2011-11-04T00:05:23Z
20111104T000523
2011-W01-2T00:05:23.283
2011-11-04 00:05:23.283

year

year( timestamp )

Returns an integer or an empty string if the timestamp is invalid.

Examples of extracting the year of a timestamp

year('2023-06-30T12:34:56.789') returns 2023. year(workflow.creationTimestamp) returns 2023 (maybe).

month

month( timestamp )

Returns the month number (an integer from 1 to 12) or an empty string if the timestamp is invalid.

Example of extracting the month of a timestamp

month('2023-06-30T12:34:56.789') returns 6.

day

day( timestamp )

Returns the day in the month (an integer from 1 to 31) or an empty string if the timestamp is invalid.

Example of extracting the day of a timestamp

day('2023-06-30T12:34:56.789') returns 30.

dayOfWeek

dayOfWeek( timestamp )

Returns the weekday (a string, from Monday to Sunday) or an empty string if the timestamp is invalid.

Example using dayOfWeek

dayOfWeek('2023-06-30T12:34:56.789') returns Friday.

dayOfWeekISO

dayOfWeekISO( timestamp )

Returns the weekday number (an integer from 1 to 7, 1 being Monday) or an empty string if the timestamp is invalid.

Example using dayOfWeekISO

dayOfWeekISO('2023-06-30T12:34:56.789') returns 5.

hour

hour( timestamp )

Returns the hour (an integer from 0 to 23) or an empty string if the timestamp is invalid.

If the timestamp only specifies a date, returns 0.

Examples of extracting the hour of a timestamp

hour('2023-06-30T12:34:56.789') returns 12. hour('2023-06-30') returns 0.

minute

minute( timestamp )

Returns the minutes (an integer from 0 to 23) or an empty string if the timestamp is invalid.

If the timestamp only specifies a date, returns 0.

Examples of extracting the minute of a timestamp

minute('2023-06-30T12:34:56.789') returns 34. minute('2023-06-30') returns 0.

second

second( timestamp )

Returns the seconds (an integer from 0 to 59) or an empty string if the timestamp is invalid.

If the timestamp only specifies a date, returns 0.

Examples using second

second('2023-06-30T12:34:56.789') returns 56. second('not a timestamp') returns ''.

Job-status check functions

You can use the following status check functions as expressions in if conditionals. If your if expression does not contain any of the status functions it will automatically result in success(). For more information about if conditionals, see “Workflow syntax for OpenTestFactory orchestrator.”

success

Returns true when none of the previous steps have failed or been canceled.

Example

steps:
  ...
  - name: The job has succeeded
    if: ${{ success() }}

always

Always returns true, even when canceled. A job or step will not run when a critical failure prevents the task from running. For example, if getting sources failed.

Example

if: ${{ always() }}

cancelled

Returns true if the workflow was canceled.

Example

if: ${{ cancelled() }}

failure

Returns true when any previous step of a job fails.

Example

steps:
  ...
  - name: The job has failed
    if: ${{ failure() }}