This is the start of a series of articles about Github actions. Mainly because I feel I have something to share, but also because I want to make a habit of writing and sharing. With that in mind, I appreciate any feedback to become a better writer. So thank you in advance :)

Before we begin, I'd like to briefly outline what topics I will be covering to give you an idea of what to expect. I will

• give a brief introduction about github actions
• set up a workflow with more detailed information
• create an action that you can run manually
• show you how you can use them in a monorepo setup
• show you how you can use reusable actions
• give some tips I wish I had known when I first started creating Github actions
• share some of the actions I have created over the last few months

I will not look into how to create your own github action that you can release on the marketplace. However, there is a great tutorial here on dev.to for that.

As you may have guessed, this will be a multi-part article and I will do my best to break it down into easily digestible reads. Again, your feedback will help a lot to make the next part better than the current one. So thanks again :)

What are Github actions

Github actions are a way to automate things provided by Github (as the name suggests). It is integrated into your repository and can be triggered by certain events, which we will cover later in this tutorial. After a trigger, we can perform various steps and do things that we normally do manually.

Why do we need them?

There are certain steps that are necessary when maintaining a codebase or building software. Some examples are:

• Running a linter to enforce a certain code style or some rules that relate to best practises
• The actual building of the software (e.g., a mobile app, a Docker image, ...)
• Running tests to make sure everything works as intended
• Running various checks to make sure your codebase is healthy

This list is not exhaustive and you probably have some ideas about what you would do in your case. Running these things automatically on a given trigger is really helpful because it obviously saves time. But it also ensures that they actually get executed. If you are working in a larger team, you can not rely on developers to perform these tasks by hand, as it can be easy to forget. Perhaps some of the tasks you want to run are difficult to do or require prior setup. With Github Actions, you can describe them once and then run them as many times as you want until you reach your quota.

How do we get started?

We start by creating what we call a workflow as a yaml file under .github/workflows in the root of your repository.

.github/
 workflows/
 lint.yml src/

Inside the yaml file, we need to define the name and jobs we want to run. Let's start with an example of linting a codebase (i.e. executing an npm command).

name: Run lint

on:
  push:
    branches:
      - master
      - develop
      - feature/*
      - hotfix/*
      - release/*

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - name: Check out codebase
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: Setup node
        uses: actions/setup-node@v3
      - name: Install depedencies
        run: npm ci # --legacy-peer-deps
      - name: Run lint command
        run: npm run lint

Let us take a closer look. First, we define a trigger. This specifies what event must occur for our actions to be executed. Here we have defined a simple push trigger and specified some branches. If a push event occurs in one of these branches, all jobs will be executed.

We can define several jobs. Each of them will be executed independently. We can specify on which machine the jobs should be executed. Here we have chosen ubuntu-latest. Within this job we have defined a series of steps that run in sequence. The name parameter specifies the name, so you can easily see the logs and know what is going on. Within the job, we specify what needs to be done. This is done in two ways.

The first way is to reuse an existing action from the Github action marketplace. These are actions that have been created by third parties. Usually we can specify parameters to customise the actions to our needs. You just need to specify the uses parameter in your workflow, followed by the action name. Check the marketplace to see what actions are available, and read the action's readme file to find out what it does and what parameters you can use. We used actions/checkout and actions/setup-node to check out our source code and create a node environment. We specified version 3 for both actions, which is the latest at the time of writing. You must always specify a version when using Marketplace actions.

The second way is to describe the tasks themselves, using the run parameter followed by the actual commands. We use it for installing dependencies and running an npm command. You can also specify a set of commands as follows:

...
steps:
  - name: Run multiple commands
    run: |
      npm run lint
      npm run test
      echo "We are done here"

There are more details on how to invoke these commands and configure your workflows, as well as best practises that I would like to show you. We will do this in a later part of this series.

I hope this brief introduction will help you understand the benefits of Github actions and the basic concepts. See you in the next article where we will discuss some details about configuring your workflows.

I have been a developer all my life and currently CTO at NanoGiants. My work involves not only programming tasks, but also strategy, tooling, and leadership. If you have an interest in a particular topic, let me know. I will consider writing about it if you find it useful :) Thank you a lot!