Conditions Reference

Overview

The Conditions DSL is a universal way of specifying conditional execution of CI/CD commands in Semaphore.

Using Conditions you can perform a full or regular expression matches and combine them with boolean operations. For example: branch == 'master' OR tag =~ '^v1\.'

Currently you can use Conditions DSL to configure following features:

Formal language definition

Formal language definition in extended Backus-Naur Form (EBNF) notation:

expression = expression bool_operator term
           | term

term = "(" expression ")"      
     | keyword operator string
     | string operator keyword
     | basic_val                  
     | fun
     | fun operator term

basic_val = string
          | boolean
          | integer
          | float
          | list
          | map

list = "[" "]"
     | "[" params "]"

params = basic_val
       | basic_val "," params

map = "{" "}"
    | "{" map_vals "}"

map_vals = key_val
         | key_val "," map_vals

key_val = map_key basic_val

fun = identifier "(" ")"
    | identifier "(" params ")"

bool_operator = "and" | "AND" | "or" | "OR"

keyword = "branch" | "BRANCH" | "tag" | "TAG" | "pull_request" | "PULL_REQUEST" |
          "result" | "RESULT" | "result_reason" | "RESULT_REASON"

operator = "=" | "!=" | "=~" | "!~"

boolean = "true" | "TRUE" | "false" | "FALSE"

string = ? all characters between two single quotes, e.g. 'master' ?

integer = ? any integer value, e. g. 123, -789, 42 etc. ?

float = ? any float value, e.g. 0.123, -78.9012, 42.0 etc. ?

map_key = ? string that matches [a-zA-Z][a-zA-Z0-9_\-]*: regex, e.g. first-name_1: ?

identifier = ? string that matches [a-zA-Z][a-zA-Z0-9_\-]* regex, e.g. foo-bar_1 ?

Each keyword in passed expression is replaced with actual value of that attribute for current pipeline when expression is evaluated, and then operations identified with one of the operators from above are executed with those values.

KEYWORD ATTRIBUTE IT REPRESENTS
branch Name of the Git branch from which originated the pipeline that is being executed.
tag Name of the Git tag from which originated the pipeline that is being executed.
pull_request The number of GitHub pull request from which originated the pipeline that is being executed.
result Execution result of pipeline, block, or job. Possible values are: passed, stopped, canceled and failed.
result_reason The reason for given result of execution. Possible values are: test, malformed, stuck, internal, user, strategy and timeout.
OPERATOR OPERATION RESULT
= True if keyword value and given string are equal
!= True if keyword value and given string are not equal
=~ True if keyword value and given PCRE* string match
!~ True if keyword value and given PCRE* string do not match
and True if expressions on both sides are true
or True if at least one of two expressions is true

* PCRE = Perl Compatible Regular Expression

Functions

The functions allow you to perform more complex checks that are not just direct boolean or regex matches.

change_in

Note: This feature is currently in beta stage of development.

The change_in function accepts one path or list of paths within the repository as a first parameter. It checks if any of those paths matches or contains one of the files that were changed in a particular range of commits.

change_in(<path>, [configuration])
or
change_in(<paths>, [configuration])

<path>  - Required, string with the absolute or relative path within the repository.
          Relative paths are relative to the location of the yml file.
          e.g. 'svcA/lib' or '/doc'

<paths> - Required, list of strings with absolute or relative paths within the
          repository. Relative paths are relative to the location of yml file.
          e.g. ['svcA/lib', '/doc', '../README.md']

[configuration] - Optional, map containing the values for configurable parameters.
                  All parameters and their default values are stated bellow.
                  e.g. {on_tags: false, default_branch: 'master-new'}

The change_in function calculates the commit range that should be examined in different ways depending on whether the workflow was initiated from the master branch or some other branch, or if it is a tag or a pull request.

The default behavior is the following:

  • On master branch the examined commit range is all the commits within the push that initiated the workflow. The same range is available in a job environment as an environment variable called SEMAPHORE_GIT_COMMIT_RANGE. The changes that are compared to the paths given as parameters in this case are equivalent to the result of git diff <sha 1>^ <sha N> command where sha 1 is the first commit of the push and the sha N is the last.

  • On other (non-master) branches the examined commit range is wider and all the commits between the head of the current branch and the common ancestor for that branch and the master branch are taken into account. The changes collected from this range are equivalent to the result of git diff master...<current branch> command and are later compared to the paths passed as parameters.

  • For pull requests the commit range of interest is from the head of the current branch until the commit that is the common ancestor for it and the branch that is the target of the pull request. The changes gathered in this way are equivalent to the result of git diff <pull request target branch>...<current branch> command and are later compared with given paths.

  • For tags the change_in always returns true if not configured otherwise.

The behavior of change_in is configurable via a map of parameters that can be given as a second parameter, as was stated above.

The supported map parameters are:

PARAMETER DESCRIPTION AND VALUES
on_tags The value of change_in function in workflows initiated by tags. Default value is true.
default_branch The default value is master. If changed to another branch, change_in will behave on that branch as it behaves by default on the master, and all other branches will be compared to it instead of to master.
pipeline_file Possible values are track and ignore, default is track. Only if track is chosen, the path to the give pipeline file will be automatically added to the paths that are given as a parameters of the change_in function.
branch_range Configures the commit range that is examined on all branches except the default one. The default value is $SEAMPHORE_MERGE_BASE...$SEMAPHORE_GIT_SHA , where $SEAMPHORE_MERGE_BASE is default branch in workflows initiated from branches or targeted branch in workflows initiated from a pull request, and the $SEMAPHORE_GIT_SHA is the sha of the commit for which the workflow was initiated. You can use here this predefined values or any literal values to create ranges in double-dot or triple-dot syntax as described here in Commit ranges section.
default_range Configures the commit range that is examined on the default branch. The default value is $SEMAPHORE_GIT_COMMIT_RANGE which behavior is described above. It accepts any commit range specified in double-dot or triple-dot syntax and same predefined values are available as stated above in the description of branch_range property.

Usage examples

Always true

blocks:
  - name: Unit tests
    skip:
      when: "true"

On any branch

blocks:
  - name: Unit tests
    skip:
      when: "branch =~ '.*'"

When branch is master

blocks:
  - name: Unit tests
    skip:
      when: "branch = 'master'"

When branch starts with “df/”

blocks:
  - name: Unit tests
    skip:
      when: "branch =~ '^df\/'"

When branch is staging or master

blocks:
  - name: Unit tests
    skip:
      when: "branch = 'staging' OR branch = 'master'"

On any tag

blocks:
  - name: Unit tests
    skip:
      when: "tag =~ '.*'"

When tag start with “v1.”

blocks:
  - name: Unit tests
    skip:
      when: "tag =~ '^v1\.'"

When branch is master or if it is a tag

blocks:
  - name: Unit tests
    skip:
      when: "branch = 'master' OR tag =~ '.*'"

When branch does not start with "dev/"

blocks:
  - name: Unit tests
    skip:
      when: "branch !~ '^dev\/'"

Still need help? Contact Us Contact Us