Conditions Reference

The Conditions DSL is a new, 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 to specify when a block should and should not run, with more applications coming soon.

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
     | string                  
     | boolean

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

keyword = "branch" | "BRANCH" | "tag" | "TAG"

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

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

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

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

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