DEV Community

Graham Vasquez
Graham Vasquez

Posted on • Updated on • Originally published at blog.gvasquez.dev

How to setup GitHub Actions on your Github repository

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.

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
Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

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 😊

Top comments (6)

Collapse
 
nicolasomar profile image
Nicolás Omar González Passerino • Edited

Great work explaining this concept. It is a great starting point to implement it without much effort.
Speaking about implementation, do you know which could be a good job config to execute a build process to deploy the final version of a page? (on angular or react, for example).

Collapse
 
gv14982 profile image
Graham Vasquez

Hi Nicolás!

This really depends on where you are going to be deploying the app. If it is on a VPS such as Digital Ocean or Linode, then you would probably just run the build script within the action and transfer the files to your server using something like scp. I know with Netlify you can give it access to your repository, and specify a build command and directory and it will handle the rest.

If you have any more info I can definitely help you out 😊

Collapse
 
nicolasomar profile image
Nicolás Omar González Passerino

My idea is to build the deploy the project using github pages. I have an angular app deployed with that service and I want to try it also with a react repo in the future.
By chance, did you have experience with this case in particular?

Thread Thread
 
gv14982 profile image
Graham Vasquez

Hi Nicolas,

I found this prebuilt Github Action that should do what you want!
github.com/marketplace/actions/dep...

Collapse
 
clickpop profile image
Chris Vasquez in October 🎃

Loved this, man. Probably the simplest overview of how to use GitHub actions I've read.

Collapse
 
gv14982 profile image
Graham Vasquez

Thanks!