Updated on 2025-08-13 GMT+08:00

Configuring Expressions

You can reference pipeline contexts with expressions to specify the execution condition of a job. An expression can be any combination of contexts, operators, functions, or literals. Contexts can be accessed programmatically with expressions, so information such as pipeline runs, variables, and jobs can be transferred across pipelines.

  1. Create a pipeline.
  2. Add stage jobs or edit existing jobs.
  3. Click Job Configuration and set Execute to With expression to configure the expression for job execution. For a new stage and job, add an extension first and then click Job Configuration.

    Figure 1 Expressions

    Example:

    The following expression shows that a job runs only when the running branch of the specified code source is master.

    ${{ sources.my_repo.target_branch == 'master' }}

References

  • Operator
    The following table lists the operators that can be used in expressions.
    Table 1 Operators

    Operator

    Description

    .

    Attribute reference. For example, the ${{ pipeline.trigger_type }} expression can be used to obtain the trigger type.

    !

    False. For example, the ${{ !startsWith(sources.my_repo.target_branch, 'release') }} can be used to check whether the branch of the pipeline's code source does not start with "release".

    ==

    Equal. For example, the ${{ pipeline.trigger_type == 'Manual' }} expression can be used to check whether a pipeline is triggered manually.

    !=

    Not equal. For example, the ${{ pipeline.trigger_type != 'Manual' }} expression can be used to check whether a pipeline is not triggered manually.

    &&

    And. For example, the ${{ pipeline.trigger_type == 'Manual' && sources.my_repo.target_branch == 'master' }} expression can be used to check whether a pipeline is triggered manually and the branch of the pipeline code source is master.

    ||

    Or. For example, the ${{ pipeline.trigger_type == 'Manual' || sources.my_repo.target_branch == 'master' }} expression can be used to check whether a pipeline is triggered manually or the branch of the pipeline code source is master.

  • Function

    The following table lists the built-in functions that can be used in expressions.

    Table 2 Built-in functions

    Function

    Description

    contains

    • Format

      contains(search, item)

    • Description

      If search contains item, this function returns true.

      • If search is an array and item is an element in the array, this function returns true.
      • If search is a string and item is a substring of search, the function returns true.
    • Example

      contains('abc', 'bc') returns true.

    startsWith

    • Format

      startsWith(searchString, searchValue)

    • Description

      If searchString starts with searchValue, this function returns true.

    • Example

      startsWith('abc', 'ab') returns true.

    endsWith

    • Format

      endsWith(searchString, searchValue)

    • Description

      If searchString ends with searchValue, this function returns true.

    • Example

      endsWith('abc', 'bc') returns true.

    format

    • Format

      format(string, replaceValue0, replaceValue1, ..., replaceValueN)

    • Description

      Replaces the value in string with the value of replaceValueN.

    • Example

      format('Hello {0} {1}', 'a', 'b') returns Hello a b.

    substring

    • Format

      substring(string, beginIndex, endIndex)

    • Description

      Returns the characters in string from beginIndex to endIndex-1. If endIndex is not configured, the characters in string from beginIndex to the end are returned.

    • Example

      substring('202412091101', 0, 8) returns 20241209.

      substring ('202412091101', 8) returns 1101.

    replace

    • Format

      replace(string, target, replacement)

    • Description

      Replaces each character same as target in string with replacement.

    • Example

      replace('hello a', 'a', 'b') returns hello b.

    completed

    • Format

      completed(job1, job2, ..., jobN)

    • Description

      Returns true when the dependent job (no job specified) or the specified job is successfully executed. For example, completed() returns true when the dependent job is completed. Or, you can set Execute to When previous job succeeds to achieve the same purpose.

    • Example

      completed ('job1', 'job2') returns true when both job1 and job2 are successfully executed.

    always

    • Format

      always()

    • Description

      Executes the current job regardless of the status of the executed dependent job. You can set Execute to Always to achieve the same purpose.

    canceled

    • Format

      canceled()

    • Description

      Executes the current job when the dependent job is stopped.

    failed

    • Format

      failed(job1, job2, ..., jobN)

    • Description

      Returns true when the dependent job (no job specified) or the specified job fails. For example, failed() returns true when the dependent job fails. You can set Execute to If previous job fails to achieve the same purpose.

    • Example

      failed('job1', 'job2') returns true when either job1 or job2 fails to be executed.

    Object filter

    You can use the * syntax to apply a filter and select matching items in a collection.

    The following is the context of a job execution.

    {
        "check_job": {
            "status": "COMPLETED",
            "metrics": {
                "critical": "0",
                "major": "0"
            }
        },
        "demo_job": {
            "status": "FAILED"
        }
    }
    • jobs.*.status indicates the status of all jobs. Therefore, ['COMPLETED', 'FAILED'] is returned.
    • Filters can be used together with the contains function. For example, contains(jobs.*.status, 'FAILED') will return true because jobs.*.status contains FAILED.