Understanding Variable Substitution

YAML itself cannot process or evaluate variables. However, many frameworks, such as in GitHub and GitLab allow the use of variables - environment variables - within YAML files which is crucial for automation scripts.

The Usage of $

In YAML, $ is just a regular character. However, remote services like GitHub and GitLab use $ to reference variables in YAML files, often for accessing environment variables.

The general approach consist of first substituting all $<variable> terms by the value of <variable> and then processing the resulting YAML script.

Example

script:
  - BRANCH=$CI_COMMIT_BRANCH

Note

GitHub also uses the ${{...}} syntax that can evaluate expressions, like scoped variables.

• This functionality is a custom tool of GitHub and not to be confused with templating languages like Jinja.

• You will use this syntax to access predefined namespaces - or contexts in the GitHub lingo - like the secrets context which can hold secrets that were set for the Organization, or Repository via the Web-UI.

• GitHub provides a set of custom functions can can be evaluated within a ${{...}} clause.

Example

env:
 BRANCH_NAME: ${{ github.head_ref || github.ref_name }}