Book Image

Automating Workflows with GitHub Actions

By : Priscila Heller
Book Image

Automating Workflows with GitHub Actions

By: Priscila Heller

Overview of this book

GitHub Actions is one of the most popular products that enables you to automate development tasks and improve your software development workflow. Automating Workflows with GitHub Actions uses real-world examples to help you automate everyday tasks and use your resources efficiently. This book takes a practical approach to helping you develop the skills needed to create complex YAML files to automate your daily tasks. You'll learn how to find and use existing workflows, allowing you to get started with GitHub Actions right away. Moving on, you'll discover complex concepts and practices such as self-hosted runners and writing workflow files that leverage other platforms such as Docker as well as programming languages such as Java and JavaScript. As you advance, you'll be able to write your own JavaScript, Docker, and composite run steps actions, and publish them in GitHub Marketplace! You'll also find instructions to migrate your existing CI/CD workflows into GitHub Actions from platforms like Travis CI and GitLab. Finally, you'll explore tools that'll help you stay informed of additions to GitHub Actions along with finding technical support and staying engaged with the community. By the end of this GitHub book, you'll have developed the skills and experience needed to build and maintain your own CI/CD pipeline using GitHub Actions.
Table of Contents (14 chapters)
1
Section 1:Introduction and Overview of Technologies Used with GitHub Actions
4
Section 2: Advanced Concepts and Hands-On Exercises to Create Actions
9
Section 3: Customizing Existing Actions, Migrations, and the Future of GitHub Actions

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.