chapter three

3 Workflows

 

This chapter covers the following topics

  • Understanding YAML and the YAML syntax
  • Learning the basics of the workflow syntax
  • Understanding workflow triggers, expressions, and contexts
  • Getting an introduction into advanced workflow concepts like workflow commands
  • Learning best practices for authoring and debugging workflows

Now that you have gained the first practical experience, it is time to fully understand the syntax for workflows.

Workflows are written in YAML. That’s why it is really important to fully understand YAML before writing workflows.

3.1 YAML

YAML stands for YAML Ain't Markup Language and is a data-serialization language optimized to be directly writable and readable by humans. It is a strict superset of JSON but with syntactically relevant newlines and indentation instead of braces. In the next sections we go through all the YAML elements that are important for writing workflows.

3.1.1 YAML Basics

YAML files are text files and have a .yml or .yaml extension. Because YAML uses indentation instead of braces these text files can be versioned very well with git as changes are always per line.

YAML files can have different encodings – but GitHub uses UTF-8 for the workflows. You can write comments in YAML by prefixing text with a hash (#):

# A full-line comment in YAML
key:value # A in-line comment

Comments can occur anywhere in a line.

3.1.2 Data types

3.2 The workflow syntax

3.3 Events and triggers

3.3.1 Webhook triggers

3.3.2 Scheduled triggers

3.3.3 Manual triggers

3.4 Workflow jobs and steps

3.4.1 Workflow jobs

3.4.2 Workflow steps

3.4.3 Using GitHub Actions

3.4.4 The strategy matrix

3.5 Expressions and Contexts

3.6 Workflow commands

3.6.1 Writing a debug message

3.6.2 Creating error or warning messages

3.6.3 Passing output to subsequent steps and jobs

3.6.4 Environment files

3.6.5 Job summaries

3.7 Secrets and variables

3.8 Workflow permissions

3.9 Authoring and debugging workflows

3.10 Conclusion

3.11 Summary