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
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.
- The
-
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.
- The
-
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
.
- The
-
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
orenvironment variables
for my code to reference. - I want to point out the
${{secrets.SECRET_NAME}}
entries I have in theenv
. 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)
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).
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 😊
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?
Hi Nicolas,
I found this prebuilt Github Action that should do what you want!
github.com/marketplace/actions/dep...
Loved this, man. Probably the simplest overview of how to use GitHub actions I've read.
Thanks!