Continuous Integration with GitHub Actions

This section will walk you through the basic setup of continuous integration (CI) using GitHub Actions (GHA). GHA is a task automation system fully integrated with GitHub. In other words, it is an API that orchestrates any workflow based on any event. Although there are many CI service providers, GHA makes it easier than ever to incorporate CI into your repositories. It provides a flexible way to automate nearly every aspect of your project workflow. Here are just a few examples of use cases of GitHub Actions:

  • Automated testing of the software

  • Generate reports of the status of any changes in the repository

  • Responding to workflow triggers using labels, issues, special mentions, and more

  • Triggering code reviews and pull requests

  • Managing branches

GitHub Actions are event-driven, which means it responds to any event (Examples: pull request (PR) created, issue created) and triggers an action (Examples: adds a label, runs tests, sort). Any collection of these actions is called a workflow. A more detailed description of this GitHub-related Vocabulary is described in the next section.

A diagram describing how GitHub action listen to an event (for example, `PR` created, issue created, PR merged) and then trigger a job which can be testing, sorting, labelling or deployment.

Fig. 48 The Turing Way project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: 10.5281/zenodo.3332807.

Getting started with GitHub Action

GitHub Actions uses YAML syntax and stored in a directory called .github/workflows in the repository. You can either use a templated workflow or create your own.

1- Using GitHub Actions template

If you want to get started with GitHub Actions, you can start by clicking the “Actions” tab in the repository where you want to create a workflow, as shown below. Under the “Actions” tab, you will find popular CI workflows, which can help deploy or automate some tasks in the repository.

A gif showing where you can find GitHub Actions template in your Github repo.

You can choose any of these starter workflows and customise them further. An explanation for building blocks within the workflow is described in a later section.

2- Using libraries-specific templates.

Github Action template is not the only starter kit available; there are libraries-specific templates for the language of interest. For example, you can use {usethis} package in R to create a template for R packages by running usethis::use_github_action_check_standard(). This will generate GitHub Actions to run CRAN checks after every commit or pull request. That’s all you have to do!

3- Using the configuration of other projects as inspiration

Many well maintained open source libraries and estableshed projects use GitHub Actions for their CI. Have a look at the checks lists on pull requests of these projects for inspiration and ideas; following by checking out their CI configuration files. In most cases their licence will allow to copy the bits that would work for your case. The advantage of this approach is to use some approaches that are already working.

For example:

In the next section, we will explain building blocks for the workflow.