GitHub Actions is a new product in the GitHub family. GitHub Actions offers a configuration-centric approach to run tasks, like a CI/CD pipeline, on defined events like tagging a new release.

GitHub Actions open a whole new world for developers to automate tasks. The product is built on Docker and you can run actions from the GitHub Marketplace or create your own, custom actions running in a container.

GitHub Actions Series Overview

GitHub Actions and Workflows

GitHub Actions is free for open source repositories. You receive 2,000 free minutes each month when running actions on private repositories.

Actions are available in a repository. Actions are described as workflows. Each workflow consists of one or multiple steps. GitHub added a button in a repository’s tab navigation:

The Actions overview page shows you all your existent worfklows and a handful of available or popular workflows which may interest you.

The superchargejs/framework repository has one existing workflow: “Run tests”.

GitHub Action Workflows

Workflows in GitHub Actions are YAML files describing each individual step. You should put the workflow files for GitHub Actions into a .github/workflows folder in your repository.

Each repository has their own workflows. You can’t define a global workflow for your organization that should run on each repository. You must define this for each individual repository.

Create a Node.js CI Workflow: Run Tests on Push

Let’s make things approachable and create a CI workflow for a Node.js application. If you’re new to GitHub Actions, you may go with a pre-defined workflow and let GitHub create the related YAML file for you. Pick a workflow in the overview page and click on the Set up this workflow button:

You can refine the workflow before committing the related YAML file to your repository. The screenshot shows the Node.js CI workflow running tests on each push.

Create a Node.js CI Workflow

Choosing the default Node.js testing workflow is a decent starting point. You may need to refine it depending on your project setup. For example, if you don’t commit a package-lock.json file to source control, the defined npm ci command fails and you need to replace it with npm install.

Here’s the default Node.js CI workflow provided by GitHub:

.github/workflows/nodejs.yml

name: Node CI

on: [push]

jobs:  
  build:

    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [8.x, 10.x, 12.x]

    steps:
    - uses: actions/checkout@v1
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v1
      with:
        node-version: ${{ matrix.node-version }}
    - name: npm install, build, and test
      run: |
        npm ci
        npm run build --if-present
        npm test
      env:
        CI: true

This GitHub Action workflow is a good starting point. As already mentioned, use npm install instead of npm ci if you don’t push the package-lock.json to source control.

Refine the Node.js CI Workflow

Let’s refine the testing workflow a bit.

At first, the name. The workflow name shows up in the list of processed actions and „Node CI“ is not that descriptive. You may change it to “Run tests”.

Second, we recommend to test against the latest Node.js version. The node-version matrix has the active Node.js LTS releases but not the “current” release line. You may add 13.x to the list.

Third, refine the testing steps. If you need your project to build frontend assets, add such a step. We like to split the steps for dependency installation and running the tests. You may go ahead and split these steps, too.

Here’s a sample GitHub Action workflow file to run tests for a Node.js on each push.

.github/workflows/run-tests.yml

name: Run tests

on: [push]

jobs:  
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [8.x, 10.x, 12.x, 13.x]

    steps:
    - name: Git checkout
      uses: actions/checkout@v1

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

    - npm install
      env:
        CI: true

    - npm test
      env:
        CI: true

Add and commit the workflow file to your repository. GitHub will pick up your CI workflow and run the defined actions. You’ll see the overview of recent runs in the “Actions” tab:

Click on one of the “Run tests” links to view the details:

Outlook

GitHub Actions are a great way to run automated tasks directly in GitHub. You can keep your CI/CD pipeline close to your code. It’s basically living inside your repository in form of a YAML file.

The next tutorial on GitHub Actions looks a defining a test matrix with a database dependency. You may want to test your project in all combinations, like all Node.js versions against a list of database versions to ensure compatibility.