GitHub Actions

GitHub Actions is a CI/CD platform made by Microsoft for GitHub.

Billing

Actions use is free for public repositories.

For free accounts, Actions has a set limit of 2000 runner minutes per month. Beyond this, GitHub will charge a per-minute rate of $0.016USD to $0.256USD depending on the size of the runner being used.

Overview

GHA is about defining Workflows, which contain Jobs, which are triggered from Events.

Workflows are defined in YAML files underneath .github/workflows in a Git repository.

Note

You won't be able to copy/paste code from here, as actions files do not allow for tab-based indentation.**

Examples and usage

name: My Cool Action # The name of the action
on: [push, fork] # Any events defined here will trigger the workflow
permissions: # Modifies the permissions accessible by the runner's token
	contents: read
jobs: ...

Jobs

A job is a set of instructions that gets run on a runner (like a container), and is contained within a Workflow.

jobs:
	build: # This is the job-id, and must be unique.
		name: Build my code # Display name
		runs-on: ubuntu-latest # See below for more info
		steps:
			# https://github.com/actions/checkout
			- uses: actions/checkout@v3
			# https://github.com/actions/setup-node
			- uses: actions/setup-node@v1
			  with:
				  # Examples: 'lts', 'latest', '12.x', '12.15.0'
				  node-version: lts
			  # Names the step in the GitHub UI
			- name: Install dependencies
			  run: yarn --frozen-lockfile
			  # Names are optional.
			- run: yarn build
	deploy:
		needs: build # Defines dependencies

runs-on

runs-on defines the type of runner to use.

GitHub-hosted runners are:

• ubuntu-latest
• windows-latest
• macOS-latest

To run a specific Docker image, use the container tag instead, like:

custom_job:
	container:
		image: node:10.16-jessie
		env: {...}
		ports: [...]
		volumes: [...]

Artifacts

Workflow artifacts are the results of builds, test results, or log files which are needed in multiple jobs.

An example might be from a build job, outputting the completed build into a deploy job.

Artifacts are saved with the actions/upload-artifact step, and are pulled with the actions/download-artifact step.

Environment variables and secrets

Variables are values for reuse between or within workflows, and are usually either publicly defined strings or secrets.

They're used within a job like the following:

steps:
	- shell: bash
	  env:
		BIG_SECRET: ${{ secrets.MyBigFatSecret }}
		USER_NAME: ${{ var.UserName }}
	  run: do-something-with "$BIG_SECRET" --as "$USER_NAME"

Or, to insert them directly into the command:

steps:
	- run: |
		do-something-with "${{ secrets.MyBigFatSecret }}"

GitHub maintains a list of default environment variables.

For more information see the API reference for variables.

Installing packages

Linux and MacOS runners are password-less, so packages can be installed without interaction.

stuff:
	runs-on: ubuntu-latest
	steps:
		- name: Install lftp
		  run: sudo apt-get install -y lftp

Events

Events define when a Workflow will run.

A workflow with one event, this will trigger on any push.

name: Any Push
on: push

A workflow with two events, this will trigger on any push or any fork.

name: Push or Fork
on: [push, fork]

A workflow with two partially configured events, this will trigger on:

• Any update or creation of a pull request
• Any push to the branch 'main'

name: Updates
on:
	pull_request: # No value needed here
	push:
		branches: # This could be an inline YAML array
		- main
		- $default-branch # The $ denotes this as a variable
jobs:
	build:
		runs-on: ubuntu-latest
		steps:
			- uses: actions/checkout@v3 # The actions/checkout builtin