GitHub Actions allow you to run code in your repository, on GitHub servers, after every push.

This can be used for many things. This article discusses how to use it for running tests (as a replacement for hosted CI services like travis.ci).

A GitHub Action is defined by a Dockerfile in some GitHub repository. Since you can have multiple actions, you create a directory for each action.

An action is triggered by a workflow description in .github/main.workflow file in a repository.

Workflow is specific to each repository, actions can be shared.

A workflow running time (a sum of all actions in a workflow) is limited to 1 hr.

Workflow

Here's the simplest workflow:

workflow "run go test on push" {
  on = "push"
  resolves = ["test"]
}

action "test" {
  uses = "kjk/siser/action-go-test@master"
}

Explaining workflow section:

• run go test on push is human-readable name of the workflow. It documents what the action is for
• on = "push" says that workflow will be executed on each push (including pushes into branches)
• resolves = ["test"] specifies a list of actions to execute. We just have one and it refers to action "test"

For a full list of options see documentation.

Explaining: action section:

• test is a name by which we can refer an action from a workflow
• uses specifies a location of the action

For more information see documentation.

Actions can be re-used. "kjk/siser/action-go-test@master" specifies an action in https://github.com/kjk/siser/tree/master/action-go-test. @master says that master branch should be used.

For simplicity I put the action in the same repository that uses the action but I could, for example, create a separate repository just for actions and re-use them in multiple repos.

Action

Actions are Docker containers (describing docker is beyond the scope of this article).

Docker containers are infinitely flexible: you can run any logic in the container.

Our goal is to simply run go test on our code.

Dockerfile describes how to build a container (with docker build).

Our action-go-test/Dockerfile is the simplest possible:

FROM golang:latest

LABEL "name"="Go test"

LABEL "com.github.actions.name"="Go test"
LABEL "com.github.actions.description"="Run go test on code"
LABEL "com.github.actions.icon"="package"
LABEL "com.github.actions.color"="#E0EBF5"

COPY entrypoint.sh /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]

There is an existing, publicly available golang:latest docker image in official Docker hub repository of images.

You can use specific versions like golang:1.11.6. We ask for the latest.

LABEL statement are for just documentation.

A file action-go-test/entrypoint.sh describes the code that will be executed when we run the container with docker run. It runs go test:

#!/bin/bash

set -e

export GOPATH=/tmp
go test

To note:

• set -e tells bash to stop execution when a command fails, as opposed to continue executing the rest of the script. If a compilation fails, you don't want to run the test. In our case we only have one command go test so it makes no difference, but it's a good habit to have in case we'll expand the script in the future
• export GOPATH= exists because our package uses go modules. golang:latest image has a working directory (where our code will be mounted) inside GOPATH and that's not allowed for modules, so we change the GOPATH

Now in the commit list you'll see:

Yellow dot means: "action execution in progress".

Green check mark means: "action finished running successfully".

Red cross means: "action failed".

When you click on them, you'll see a short summary of checks:

Link details points to a page like https://github.com/kjk/siser/runs/81810467 showing a log of action execution.

Actions can do a lot more. See awesome actions list and actions in GitHub Marketplace for more inspiration.