Basics of Github Actions

The core of Github Actions are workflow files found in a repository. These workflow files are stored in the folder .github/workflows and are automatically read by Github.

Before we dive into the common workflows in Github Actions, let's first understand the high-level anatomy of Github Actions.

Anatomy of Github Actions

Workflows are configurable automated processes designed to run when an event occurs. These events may include things creating a pull request or when an issue is created. A single workflow may be triggered by different events, and it may have certain restrictions being placed on it (for example, a workflow triggered by a pull request will only run when the target branch is the main branch).

Each workflow is comprised of one or more jobs. Jobs are essentially units of work within the workflow. Jobs can either run in sequential order or in parallel (if one depends on the other). Every job runs within its own runner which is a virtual machine or a container.

You are able to pick between using a virtual machine to execute a job (default) or a Docker container. This guide will not focus on the nuances behind choosing one over the other.

Each job is comprised of several sequential steps that either execute some script defined or an action, which are reusable extensions.

Because steps execute within the same job (and thus the same runner), they can share data between one another through the shared virtual machine/container filesystem. However, because jobs run in different runners, they do not have direct access to the same virtual machine/container filesystem. There are other ways to share data between jobs that we will discuss in one of the common workflows.

The above content is taken from the official Github Actions documentation on the components of Github Actions. https://docs.github.com/en/actions/about-github-actions/understanding-github-actions

Example application

To allow you to get a glimpse of what it is like working with Github Actions and setting up various pipelines in Github Actions, we have prepared a simple example React application for you.

End goal

The goal of this guide would be for you to add various Github Actions workflows to this example application and extend off of it.

So, throughout a few hands-on activities, you will get the opportunity to build a common CI/CD pipeline to automatically test, lint, and deploy the application.

Structure

It is a simple React app created with Vite, built using Typescript, and styled with Tailwind CSS. It is a very simple calculator application that allows you to add/subtract/divide/multiply two numbers — x and y — and display the output:

The calculations are performed using a utility class calculator.ts and there is a unit test suite calculator.test.ts that we have provided as well.

Everything else is not that relevant and you are free to gloss over them if you want.

Setup

Fork the repository

https://github.com/woojiahao/cicd-calculator

Clone the repository

git clone https://github.com/<your Github username>/cicd-calculator

(Optional) Run the repository

yarn
yarn dev

You do not need to run the project locally since we will be focusing on writing Github Actions workflows, which will not require running the project locally.

As you go through this section, we will be building on top of this existing project, adding Github Actions and exploring the concepts discussed above.

(Optional) Setting up act

As you work through this section, you may want to test your Github Action workflows locally before pushing them to Github (to conserve the minutes). You may use the act tool to do so.

The installation instructions for act can be found here: https://nektosact.com/installation/index.html

There are several limitations to using act , such as not having direct access to an actual Github environment, and it does not also simulate/work for every event type. So use it just for understanding the basics of Github Actions.