How to setup GitHub Actions on your Github repository
Tags: github, tutorial, devops
Published: 2020-11-09 19:14:10

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](https://github.com/features/actions) is the built in automation feature on Github. There are other third-party solutions such as [CirclCi](https://circleci.com/) and [TravisCi](https://travis-ci.org/) 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](https://github.com/GV14982/async-airtable), <small>If you want to know more, check out my write up.</small> {% link https://dev.to/gv14982/making-intneracting-with-the-airtable-api-even-easier-1lm5 %}

# 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](https://yaml.org/), 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!

- <H5>name</H5>
  - The `name` field is just used to name the workflow on Github.
- <H5>on</H5>
  - 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.
- <H5>jobs</H5>
  - 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`.
- <H5>job</H5>
  - For each job you need to specify some information. This information includes:
    - <H5>runs-on</H5>
      - 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 😅)
    - <H5>steps</H5>
      - 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](https://docs.github.com/en/free-pro-team@latest/actions/reference/encrypted-secrets)

# 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](https://docs.github.com/en/free-pro-team@latest/actions).

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