Introduction to YAML

GitHub Actions workflows must be written using the YAML syntax. For this reason, having a strong understanding of how YAML works is essential to create successful workflow runs.

According to the website YAML.org, "YAML is a human friendly data serialization standard for all programming languages." YAML is commonly used in configuration files, much like the files used to create GitHub Actions and workflows.

Basic rules

The following file, copied from the open source repository found at https://github.com/actions/starter-workflows, shows how a YAML file is used to create a GitHub Actions workflow:

name: Close as a support issue
on:
  issues:
    types: [labeled]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Close Issue
      uses: peter-evans/close-issue@v1
      if: contains(github.event.issue.labels.*.name, 'support')
      with:
        comment: |
          Sorry, but we'd like to keep issues related to code in this repository. Thank you 
          
          If you have questions about writing workflows or action files, then please [visit the GitHub Community Forum's Actions Board](https://github.community/t5/GitHub-Actions/bd-p/actions)
          If you are having an issue or question about GitHub Actions then please [contact customer support](https://help.github.com/en/articles/about-github-actions#contacting-support)

Key-value pairs and case sensitivity

Most elements in YAML are based on key-value pairs, commonly noted as KVPs. You can observe the KVP syntax in the preceding file and it is shown again here:

name: Close as a support issue

KVPs must be written in following the key: value syntax. Note how there is a space between the colon and the value. Neglecting to include the space will cause failures when your configuration or job runs.

If the key-colon-space-value syntax is respected, KVPs in YAML can be quite flexible.

YAML is also case-sensitive. Therefore, keys such as Another-Boolean and another-boolean are considered valid.

Indentation and the use of tabs

Note the following excerpt from the YAML file shared previously:

on:
  issues:
    types: [labeled]

Indentation in YAML is used to denote structure. In other words, items with the same indentation are considered siblings, while items with indentation are considered a child or a parent. In the preceding example, on is the parent of issues, which is the parent of types.

Important note

YAML does not use tabs. Indentation is created by using spaces. You may want to consider configuring your text editor to show white spaces, which may be helpful while writing YAML files.

Comments

YAML accepts comments. To add a comment, start by adding a hashtag, or pound sign (#). For example, this is what adding a comment to the YAML file pasted previously would look like:

#adds a name to the workflow
name: Close as a support issue
on:
  issues:
    types: [labeled]
#creates the job and build
jobs:
  build:
    runs-on: ubuntu-latest
    steps:

YAML components

While this book will not cover a comprehensive list of YAML components, three of the most used ones are outlined next.

Scalars

Scalars are defined by integers, floats, strings, and Booleans. Given the flexibility that YAML provides, all the following are acceptable:

integer: 10
#different ways to write booleans
boolean: true
another-boolean: yes
yet-another-boolean: off
a key with spaces: a value with spaces
#different ways to write strings
string-with-quotes: "a string with quotes"
string-without-quotes: a string with quotes
new-lines-are-kept-as-new-lines: |
  This is line number 1, and it will show exactly this way
  This is line number 2, and it will show exactly this way
  This is line number 3… you get it
multi-lines-here-that-will-render-as-one-line: >
  When you want a block of text made of many lines
  To show all in one single line
  You can use the special character greater than

Sequences

Sequences are also known as lists of data. Items in a sequence are identified by the dash-space-item syntax. The following workflow file has an example of a block sequence:

    runs-on: ubuntu-latest
    steps:
    - name: Close Issue

Mappings

Mappings allow for the creation of more complex structures, using a combination of sequences and scalars. Note how the following example has scalars (strings) and a sequence (list):

    steps:
    - name: Close Issue
      uses: peter-evans/close-issue@v1
      if: contains(github.event.issue.labels.*.name, 'support')
      with:
        comment: |
          Sorry, but we'd like to keep issues related to code in this repository. Thank you 
          
          If you have questions about writing workflows or action files, then please [visit the GitHub Community Forum's Actions Board](https://github.community/t5/GitHub-Actions/bd-p/actions)
          If you are having an issue or question about GitHub Actions then please [contact customer support](https://help.github.com/en/articles/about-github-actions#contacting-support)

Well done! You have reached the end of Chapter 1. The knowledge you have gathered in this chapter will be fundamental in understanding core concepts of GitHub Actions and successfully putting them into practice.