A tutorial on Github Actions

Github Actions is a CI/CD service created by Github. It aims to make it easy to automate all software workflows, now with world-class CI/CD. Build, test, and deploy code right from GitHub. It was launched in October 2018 and was officially available to all users in November 2019.

This post will give an introduction of Github Actions and explain how it works.

What is Github Actions

Normally Continuous Integration includes some steps, fetching code, running test, sshing into remote server instance, deploying code/binary on remote server etc. They are called actions in Github Actions.

Lots of Github projects actually share some common steps like above. Github noticed this phenomenon and created this flow to allow developers to put these operations into separate scripts and save into repositories so that other developers can reuse. Hence the CI process is a combination of different actions.

If you want to include an action, it doesn't necessarily mean that you need to write the action by yourself, there is a chance where others have already created one and you can reuse their work. Github has built a market place for these actions where people can find other's actions.

Syntax

Github Actions has its own terminologies.

workflow: The flow executed by the CI tool when it starts.
job: A workflow consists one or more jobs. It refers to the tasks in one workflow execution.
step: A job consists of one or more steps which executes one by one
action: Each step consists of one or more actions. The smallest execution unit.

The configuration file for Github Actions is called workflow. It is usually stored in .github/workflows folder. workflow file adopts YAML format, it can have any name with extension .yml such as foo.yml. One repository can have more than one workflow file, Github will execute these files as long as it finds them.

There are lots of terms in a workflow file. The details can be found in its official documentation. Below lists some basic ones.

name

name indicates the name of the workflow, if no name is specified, the name of the workflow file will be the workflow name.

name: GitHub Actions Demo

on

on defines the condition when the execution will be triggered. Usually triggered by some events.

on: push

Above means trigger the execution on pushing the code.

on conditions can also be an array.

on: [push, pull_request]

Above means either push or pull_request can trigger the workflow execution.

on.[push|pull_request].[tags|branches]

When defining the trigger event, can also specify the branch or tag the condition is on.

on:
  push:
    branches:    
      - master

Above code indicates the execution is triggered only when push happens on master branch.

jobs.[job_id].name

The major components of a workflow is the job. Each job needs to have a job id. The name is the description of the job.

jobs:
  my_first_job:
    name: My first job
  my_second_job:
    name: My second job

Above workflow contains two jobs: my_first_job and my_second_job

jobs.[job_id].needs

needs defines the dependency relationship among jobs.

jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

Above means job1 needs to complete first before job2 starts. And job3 will start only after job1 and job2 complete.

jobs.[job_id].runs-on

runs-on defines the virtual environment the execution happens on. It is a compulsory field. Available environments are:

ubuntu-latestï¼Œubuntu-18.04 or ubuntu-16.04
windows-latestï¼Œwindows-2019 or windows-2016
macOS-latest or macOS-10.14

Below statement specifies the environment as ubuntu-18.04.

runs-on: ubuntu-18.04

jobs.[job_id].steps

steps define the steps for the job execution. A job can have one or more steps. It can have name, run and env fields.

name: Name of the step
run: The command to be executed
env: Environment variables needed for the execution.

Example

Below is a complete workflow file.

name: Greeting from Mona
on: push

jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:
    - name: Print a greeting
      env:
        MY_VAR: Hi there! My name is
        FIRST_NAME: Mona
        MIDDLE_NAME: The
        LAST_NAME: Octocat
      run: |
        echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.

The above workflow will run a job named my-job on the latest Ubuntu environment when the code is pushed. It consists one step only and it will print the name.