Introduction to GitHub Actions

GitHub actions is a way to execute one or more tasks every time a certain event occurs. For example, setting reviewers (the task) every time a PR is being opened (the event).

How do I use them?

By creating workflows. A workflow is a .yml file that (a) defines the events that we wish to listen for and (b) describes the jobs that are going to be executed. A job is the task that was mentioned earlier and consists from one or more of steps. Now a step is either a command or an action but more on that in a bit.

Lets see a simple workflow to clarify those definitions:

This is a workflow named Check PR that runs every time there is a new or updated PR and executes two jobs (here in parallel but can be configured to execute them sequentially):

• The first job, named check-pr-quality, has 6 steps and in each one runs the echo command to print a message.
• The second job, named set-reviewer, has 2 steps and, as in the first one, it runs the echo command in each step to print a message.

Admittedly, this is not a valuable workflow but it is a valid one! Just copy and paste it in a .yml file inside your repository under the .github/workflows folder (this is where all workflows should be added) and then create a new PR. After pushing it to GitHub go to the Actions tab you will see something similar to this:

What’s happening under the hood is that for each job:

• a new and clean instance of Ubuntu (configured by runs-on key) is being boot up in a virtual machine
• some necessary environment variables are being set up, and
• we get “landed” in the /home/runner/work/our-repo-name/our-repo-name (no need to remember it, you can use the GITHUB_WORKSPACE environment variable) path ready to start executing the defined steps

Steps

As mentioned earlier a step can either be a command or an action.

A command is everything that can be executed inside the OS. Let’s not forget that we are inside a virtual machine with various tools installed. We can run from simple bash commands like the one we saw (echo) to multiple ones that help as install and run extra software. For example:

- run: |
    curl -s "https://get.sdkman.io" | bash
    source "$HOME/.sdkman/bin/sdkman-init.sh" && sdk install kotlin

this snippet installs sdkman and then uses it to install kotlin. So now our Ubuntu instance has Kotlin!

An action is what we’ll use when a couple of commands won’t be enough. Think of an action like a full fledged program that can have inputs, produce outputs and can be programmed to do pretty much whatever we want.

Lets change the first job in the workflow above by replacing all echo commands with actions and commands that will actually do what was previously just described:

As before we have a workflow which executes a job that consists from 6 steps.

Only this time we use an action to download our repository to GITHUB_WORKSPACE, an action to setup our java environment, a couple of commands to compile and test our project now that we have it in our workspace (gradlew is part of our project) and an action that will run ktlint and make comments on our PR if there are any errors.

Summary

Think of it like being in a terminal, running and combining multiple commands to produce a result. A job is that terminal and actions are those commands. Mix and match them to automate whatever takes time in your processes.

For more on GitHub actions you can read its documentation, do some of the official training or start reading the code of all those available actions in the marketplace!