Using GitHub Actions

There are lots of things you can use GitHub Actions for. I used them because I saw on some open source projects that when you sent a PR, it ran some tests and I wanted to know how you do that.

On my project I have it running Jest and Cypress tests, and they're set up a little differently, so it's useful to go through them both.

Setting up an action

GitHub makes this look harder than it is.

In your repo, click on Actions, at the top (it's after Code, Issues and Pull Requests).

Ignore all the suggested workflows and click on the link at the end of the paragraph of text to set up a workflow yourself.

The cool thing is that GitHub creates an action for you with comments about what is going on. By default it runs when you push or pull request to the main branch. So if you press Start commit at the top right, it will save the file by pushing it to the main branch, which means the script runs.

Now if you go to the Actions tab you'll see your action there. If you click on the commit text it will give you some information about the action. If you click on the white box it'll show the terminal output of everything it did.

If you go back to your code you'll see at the top there's now a folder called .github/workflows. In there, will be your action.

Jest

If you followed the previous step this will look very familiar, as I started with the example:

name: Jest Testing

on:
  # Triggers the workflow on push or pull request events but only for the main branch
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

jobs:
  test:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v2

      # Runs a single command using the runners shell
      - name: Install
        run: npm install

      # Runs a single command using the runners shell
      - name: run test
        run: npm test

As with the test action GitHub created, this runs on push or pull request. The important part here are the last two bits with a name and run. This is the format it needs, with a run beneath a "- name". You can name it whatever you like, as long as it describes what it's doing.

What it is doing is acting like it's just downloaded/cloned your repo, so needs to install all your dependencies. And then it's running the Jest test - npm test is exactly what I type in to run tests on my computer.

When you push it, it takes a little while to run, understandably since it's installing dependencies. But the best way to see it at work is to create a pull request. You can watch it running tests and it won't let you press the Merge button until they've all passed.

Cypress

This is set up differently, because it uses their template.

name: Cypress testing

# Controls when the workflow will run
on:
  # Triggers the workflow on push or pull request events but only for the main branch
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

jobs:
  cypress-run:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      # Install NPM dependencies, cache them correctly
      # and run all Cypress tests
      - name: Cypress run
        uses: cypress-io/github-action@v2
        with:
          build: npm run build
          start: npm start

The difference here is that I'm using cypress-io/github-action@v2, so I don't have to tell it to install everything and run tests, just how to build and start my app. Then to run the tests it looks for a script in your package json called start:ci which tells it how to run the tests. The text in here is that same as you'd use to run cypress, eg npx cypress run.

And that's it, it runs on push or pull request.

That's it

Are there more (complicated) things you can do with GitHub Actions? Probably. I know you can use them to re-build when you update main, so then your live site is always up-to-date. But most of my stuff is on Netlify, which does that itself. I'm still finding the ability to run a script on a push or pull request pretty cool without it doing anything particularly exciting.

If you have an open source project it would be pretty useful to know that GitHub is doing the checking that the contributors haven't broken any tests without having to check it all yourself. Of course if they've written something new that the tests don't cover then it doesn't help - you'd need something else to check for coverage.