1. General info
Why would you like to run your GitHub Actions locally? This is useful for a couple of reasons:
- No need to commit and push every time you want to test workflow changes.
- You can use
act
to additionally automatize your processes.
This post is heavily based on nektos/act GitHub project, with additional things that I struggled with in order to make it work as it is on GitHub.
2. Linux installation
The act
project uses the Docker API to pull and build the necessary images. Also,
brew
is used as a package manager for Linux, check Brew for Linux.
To install Docker on Linux visit this link
and for Windows check this link.
Next we will see the installation of the required code on a Linux machine.
2.1. Install docker
-
Remove old versions of Docker (if you don't have Docker, it will do nothing).
$ sudo apt-get remove docker docker-engine docker.io containerd runc
-
Set up the repository.
sudo apt-get update sudo apt-get install ca-certificates curl gnupg lsb-release
-
Add Docker official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
-
Use the following command to set up the stable repository. To add the nightly or test repository, add the word nightly or test (or both) after the word stable in the commands below.
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
-
Install Docker engine:
sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io
Try if docker works:
docker run hello-world
If the systems complains about the permissions run the following commands:
sudo groupadd docker
sudo usermod -aG docker ${USER}
Then log out, log in and restart docker:
sudo -i
exit
sudo systemctl restart docker
Try if docker works, if it complains again set mod for the docker daemon:
sudo chmod 666 /var/run/docker.sock
After this the docker run hello-world
should run.
2.2. Install brew
Brew can be installed by a single command given in the brew website.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
After which, don't forget to read the info, the installation asks you to run commands:
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> /home/${USER}/.profile
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
sudo apt-get install build-essential
2.3. Install act using brew
This is basically a single command:
brew install act
3. Using act
You are ready to run act
, but before running it you must download the Docker image
that can run most of the GitHub Actions. If you try to run act it will offer you one
of the default docker images. The default images do not contain all the tools that
GitHub Actions offers by default in their runners. Many things can work improperly or
not at all while running those image, as it is said in the
GitHub nektos/act Readme.
3.1. Pull the docker image
Nektos provides an environment that works just like the corresponding GitHub runner. You can use docker to download the image (size is 18.2GB extracted and 6.34GB for download):
docker pull nektos/act-environments-ubuntu:18.04
After downloading the image you can check it.
docker images --all
Where docker will return something like
REPOSITORY TAG IMAGE ID CREATED SIZE
hello-world latest feb5d9fea6a5 2 months ago 13.3kB
nektos/act-environments-ubuntu 18.04 8aaea77c344b 22 months ago 18.2GB
3.2. Configure act
Configuration of images for act are in ~/.actrc
. If you pulled the default images
this file will look something like bellow. To this file add the line (shown here
as the latest line) that adds the pulled image to the configuration.
-P ubuntu-latest=node:12-buster-slim
-P ubuntu-20.04=node:12-buster-slim
-P ubuntu-18.04=node:12-buster-slim
-P ubuntu-18.04-ghact=nektos/act-environments-ubuntu:18.04
3.3. Run act
Now you can run act with full support of GitHub Actions. Workflows in github are defined
in the .github/workflows
folder in .yml
files. The blank.yml
you get from GitHub
explains the basic commands:
# blank.yml
# This is a basic workflow to help you get started with Actions
name: CI
# Controls when the workflow will run
on:
# Triggers the workflow on push or pull request events but only for the master branch
push:
branches: [ master ]
pull_request:
branches: [ master ]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
# This workflow contains a single job called "build"
build:
# The type of runner that the job will run on
runs-on: ubuntu-latest
# Steps represent a sequence of tasks that will be executed as part of the job
steps:
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
- uses: actions/checkout@v2
# Runs a single command using the runners shell
- name: Run a one-line script
run: echo Hello, world!
# Runs a set of commands using the runners shell
- name: Run a multi-line script
run: |
echo Add other actions to build,
echo test, and deploy your project.
- name: Extract branch name
shell: bash
run: echo "##[set-output name=branch;]$(echo ${GITHUB_REF#refs/heads/})"
id: extract_branch
if: github.ref == 'refs/heads/master' || contains(github.ref, 'refs/heads/release_')
The first thing to do when making a local GitHub actions runner is to define
the runs-on
parameter which for our docker image is ubuntu-18.04-ghact
.
After that you would like to run this yaml file only locally from act. This
can be achieved by setting custom on
parameter, for example locally
. With
these basic settings you can make the following folder structure in your git
repo, with the file local_actions_demo.yml
that runs locally:
my_repo/
├── .git/
└── .github/
└── workflows/
├── local_actions_demo.yml
└── actions.yml
The content of the local_actions_demo.yml
is as following.
# local_actions_demo.yml
name: GitHub Actions Demo
on: locally
jobs:
Explore-GitHub-Actions:
runs-on: ubuntu-18.04-ghact
steps:
- run: echo "🎉 The job was automatically triggered by a ${{ github.event_name }} event."
- run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by GitHub!"
- run: echo "🔎 The name of your branch is ${{ github.ref }} and your repository is ${{ github.repository }}."
- name: Check out repository code
uses: actions/checkout@v2
- run: echo "💡 The ${{ github.repository }} repository has been cloned to the runner."
- run: echo "🖥️ The workflow is now ready to test your code on the runner."
- name: List files in the repository
run: |
ls ${{ github.workspace }}
- run: echo "🍏 This job's status is ${{ job.status }}."
In order to run only the local_actions_demo.yml
run the following command from
the my_repo
folder:
act locally
This means that only actions that have the on: locally
parameter set will run.
Finally, you're good to go and do all the wild experimenting on your local machine
without the need to commit/push to GitHub every time.
It is possible to run act with an existing image without the need to have the image
set up in the .actrc
file. Just add the image line from .actrc
to the command
line when calling act:
act locally -P ubuntu-18.04-ghact=nektos/act-environments-ubuntu:18.04
3.4. Using artifacts
If you want to use the artifacts mechanism in github actions, that are
actions/upload-artifact@v2
and actions/download-artifact@v2
, you must supply
the following command argument:
act locally --artifact-server-path /path/to/artifact_folder
where artifact_folder
is the folder where the artifacts will be saved.