Writing software is pretty fun, but there are lots of menial tasks that can get annoying. Things like testing, handling deployments, and other small tasks can take away from the fun of writing code. That's why you should automate those tasks!

But what are Github Actions?

Github Actions is the built in automation feature on Github. There are other third-party solutions such as CirclCi and TravisCi which follow the same general idea.

To start with Github Actions, you first need a Github repository! In this tutorial we are going to be working with my existing project, AsyncAirtable, If you want to know more, check out my write up.

Making interacting with the Airtable API even easier

Graham Vasquez ・ Nov 1 '20

#javascript #npm #node #database

Alright, well how do I set them up?

Directory structure

So to get started with github actions you need to create a .github folder in your repository. Within that folder you want to create a workflows folder. So your repo file structure should look like this:

repo/
├── .github/
│   └── workflows
└── ...code

Cool, so now that we have the folder setup, lets take a look at our workflow files.

Workflow yaml files

Github Action workflow files are written in yaml, which is a super easy to read and write. So let's take a look at a workflow yaml file and then break it down!

name: Tests

on:
  push:
    branches:
      - develop
  pull_request:
    branches:
      - master

jobs:
  test:
    strategy:
      max-parallel: 1
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]

    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v2
      - name: Setup Node
        uses: actions/setup-node@v1
        with:
          node-version: 12
      - name: Install
        run: npm install
      - name: Run tests
        run: npm test
        env:
          AIRTABLE_KEY: ${{secrets.AIRTABLE_KEY}}
          AIRTABLE_BASE: ${{secrets.AIRTABLE_BASE}}
          AIRTABLE_TABLE: 'tests'
          TEST_FILTER: "{email} = 'same@test.com'"
          NEW_RECORD: '{"title": "test-create", "value": 23, "email": "new@test.com"}'
          UPDATE_RECORD: '{"title": "test-UPDATED"}'
          DESTRUCTIVE_UPDATE_RECORD: '{"title": "test-UPDATED-destructive", "value": 23}'
          RETRY_TIMEOUT: 60000
          REQ_COUNT: 100

Let's break this down!

• name

  • The name field is just used to name the workflow on Github.

• on

  • The on field is used to express when you want this workflow to run.
  • In this case I have it running every time code is pushed to my develop branch, or a pull request is created on my master branch.

• jobs

  • The jobs field specifies the jobs you want to run in the workflow.
  • The jobs are listed by name. In this case, my job is called test.

• job

  • For each job you need to specify some information. This information includes:

  • runs-on

    • The operating system the job runs on.
    • In this case I specified a matrix that is an array of operating systems to test my code on all 3 major operating systems. I also make it so only one job can be run at a time using the max-parallel field. (This is due to a constraint with the API I'm talking to 😅)

  • steps

    • These are the commands the job will actually run.
    • These can either be terminal commands or other actions you can reference.
    • The uses field is used to denote a reference to another published github action. In this case I am use the checkout action that loads the code from my repository into the workflow, and a node setup action.
    • For the other steps I am just running my npm terminal commands, and specifying env or environment variables for my code to reference.
    • I want to point out the ${{secrets.SECRET_NAME}} entries I have in the env. These are secrets you can add to your Github repository. In this case, they are my API key and base name. Check out more here

Wrap-up

And that is the basics of a workflow file for Github Actions. If you want to know more, be sure to check out the Github Actions Docs.

Feel free to reach out to me if you have any questions and I hope you enjoy automating all those lame tasks 😊