Create a simple GitHub Actions Workflow

If you are trying to build any software project you definitely need an workflows to build and test your project. GitHub Actions workflow can help you by automating, customizing and executing the workflow itself.

In this post, we're going to create a simple GitHub action workflow that will check the build status and test the code every time someone pushes the code or creates the pull request.

Let try to understand first the concepts related to GitHub action workflow.

GitHub Actions Workflow Building Blocks

• Workflow: The workflow define the specific automation procedures, instructions and actions which run after an event is triggered or scheduled. The workflow is written in the .yml(YAML) file which is created in the project repository itself.
  
  

• Workflow Triggers: Triggers are the events that will decide when the GitHub workflow will run. These triggers can be of four types. These are :

  • Manual trigger.
  • A predefined schedule.
  • Events happening in the workflow’s GitHub repository.
  • Events occurring outside of GitHub, which trigger a repository dispatch event in GitHub.

• Runners: The workflow requires an environment where it can be executed. For example if we build or test our project we use our own environment usually it is a dedicated system that we are using. Just like our dedicated system Runners are servers where the workflow will be executed. Runner are always listening for events to trigger the workflow.

• Jobs: Jobs are pretty much self explanatory they contain a series of steps that runs within the runners environment. Every workflow needs at least one job. By default the jobs under the same workflow runs in parallel.

• Actions: Actions are the smallest unit. The actions of a job are specified with the steps syntax. Each step can have a name, own environment variables, and commands to run.

Okay now as we know enough about the basic terminologies of workflow, we can get back to create simple GitHub action workflow.

GitHub Actions Workflow Example

1) In your project repository create a dedicated directory to store workflow files. The directory must be named as -.github/workflows This directory is where GitHub will look for the workflow files.

2) Create a .yml file in github/workflows directory. You can name this file anything you like but for now, we are naming it as main.yml.

3) Now add a name of the workflow for example use the following line at the beginning of the main.yml file:

name: check-build

4) Add on attribute which will tell GitHub when to run the the workflow. In our case we want to run the workflow when code is pushed or there is a pull request. use the following lines on your main.yml file.

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

5) Now we want to create two jobs one for checking the build and another for testing the code. Let start with check-build jobs that will contains the following steps and run-ons attribute:

jobs:
  check-build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: ['14']
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: ${{ matrix.node }}
      - run: npm install
      - run: npm run build

run-ons attribute as described earlier will decide which environment the build will be created. Now if you focus on the steps attribute has two run attribute to execute the commands npm install and npm run build which is exactly how you would do it in your local system.

6) Lets move on the testing the code that should check if the code contains any lint issues, formatting issues or check if any of the test are failing. For this we will create a check-code job that will contain the following steps:

check-code:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: ['14']
    name: Prettier on Node ${{ matrix.node }}
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: ${{ matrix.node }}
      - run: npm install
      - run: npm run prettier:check
      - run: npm run eslint --ext .ts ./src
      - run: npm run test

Note The above code assumes that you have setup prettier and eslint in your project.

7) Now the final workflow main.yml file should match the following gist:

8) Now finally you can commit your code and push it to the GitHub.

9) You can further check the build status in your code repository Action tab.

Thanks for reading this Create a simple GitHub Actions Workflow blog. I hope it has been a helpful read.