GitHub Actions

What are GitHub Actions?

GitHub actions are a way to quickly automate software development workflows. As a developer, there are a lot of tedious and repetitive tasks that must be done to keep an app organized and managed when trying to deploy or do pre-deployment steps. Some of these tasks include checking pull requests, merging a branch back in with the main branch, testing, building, deploying, adding new contributors, dealing with user-submitted issues (assigning, labeling, trying to reproduce bugs).

There are so many tasks to complete, especially with a growing or larger project, that it is to our advantage to automate as many of these tasks are possible so that the devs have more time to concentrate on the actual coding and functionality of the project.

Events

When something happens in or to your repo, these are called events. GitHub actions will respond and execute designated workflows when specified events occur. Some examples of events that you might have GitHub actions listen for are creations of new pull requests, merging of pull requests, new contributors joining the project, and creation of issues.

If the event was a new issue created by a user, you might have a workflow that sorts that issue by the level of severity, labels it, assigns it to a developer, or tries to reproduce the reported bug. This triggered workflow would be composed of GitHub actions that would run each of these desired steps.

A Quick Look

Let’s walk through an example workflow file. GitHub offers many templates to choose from. You can view them by simply clicking on the Actions tab from your repository.

GitHub Action tab default view

Here I’ve decided to select the option on the right — Node.js. This workflow is designed to “Build and test a Node.js project with npm.”

When you click “Set up this workflow” you will be presented with a file that looks like this:

# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node
# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
name: Node.js CI
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
jobs:
  build:
runs-on: ubuntu-latest
strategy:
      matrix:
        node-version: [10.x, 12.x, 14.x, 15.x]
        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
steps:
    - uses: actions/checkout@v2
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v2
      with:
        node-version: ${{ matrix.node-version }}
    - run: npm ci
    - run: npm run build --if-present
    - run: npm test

By default, this file will be a .yml file created in your root folder in a directory called .github/workflows. You can designate whatever name you choose for the file itself.

Let’s break down this file.

name: Node.js CI

This line simply designates a description of the workflow.

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

The lines in the on section designates the events that trigger the workflow. This workflow would be triggered on both push requests to the main branch, and pull requests to the main branch.

jobs:
  build:
runs-on: ubuntu-latest
strategy:
      matrix:
        node-version: [10.x, 12.x, 14.x, 15.x]
        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/

This section specifies the action that will be taken on push and pull requests to the main branch, in this case, a build action.

runs-on specifies the environment for which this build will need to work. You can specify multiple environments if you wish using matrix. You can see this at work in the strategy section. strategy shows the node versions that should be acceptable for this build.

steps:
    - uses: actions/checkout@v2
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v2
      with:
        node-version: ${{ matrix.node-version }}
    - run: npm ci
    - run: npm run build --if-present
    - run: npm test

The steps section is the actual run-down of specifications in order to do the build. Here we start with uses: actions/checkout@v2. This line specifies that we will use the pre-defined action called checkout (version 2). This action actually checks out your repository and prepares it in a new virtual environment in order to run this workflow.

name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v2
      with:
        node-version: ${{ matrix.node-version }}

These lines instruct using the node versions specified in the strategy matrix in the pre-defined action setup-node (version 2).

    - run: npm ci
    - run: npm run build --if-present
    - run: npm test

Then, last but not least, the workflow will run these 3 commands, npm ci, npm run build --if-present and npm test.

For each job, GitHub Actions prepares a new virtual environment so you don’t have to worry about any cross-contamination. These jobs run in parallel by default, but you can run consecutively instead, overriding the default with the line needs: <name of previous job required> in the successive jobs.

Summing It Up

GitHub Actions are a great way to quickly automate tasks that you will need to perform on a regular basis. Since you already have your repository hosted on GitHub you have one less tool to use, instead of relying on another third-party integration. The setup is very minimal due to their templates and pre-defined actions. A lot of different technologies can be used in tandem with the differently configured workflows available.