using act to run github actions locally

act is a tool that lets you run github actions locally. it’s useful for testing and debugging workflows without pushing to your repo.

problem

testing github actions can be slow and cumbersome. each change requires a commit, push, and wait for the action to run on github’s servers.

solution

act allows you to run actions locally, speeding up the development cycle and reducing the load on github’s servers.

installation and setup

install act on mac using homebrew:

install-act
brew install act

ensure docker is installed and running, as act uses it to simulate the github actions environment.

mac m1 installation

architecture error

architecture-error
INFO[0000] Using docker host 'unix:///Users/outatimedev/.docker/run/docker.sock', and daemon socket 'unix:///Users/outatimedev/.docker/run/docker.sock'
WARN  ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠
[CI/Build, Push, and Deploy] 🚀  Start image=catthehacker/ubuntu:act-latest
[CI/Build, Push, and Deploy]   🐳  docker pull image=catthehacker/ubuntu:act-latest platform= username= forcePull=true
^CError: context canceled

to solve just add --container-architecture linux/amd64 to your act command:

mac-m1-installation
act --container-architecture linux/amd64

docker socket error

docker-socket-error
Error: failed to start container: Error response from daemon: error while creating mount source path '/host_mnt/Users/outatimedev/.docker/run/docker.sock': mkdir /host_mnt/Users/outatimedev/.docker/run/docker.sock: operation not supported

figure out which socket is being used by docker:

find-docker-socket
➜  outatime git:(master) ✗ docker context ls
NAME              DESCRIPTION                               DOCKER ENDPOINT                                      ERROR
default           Current DOCKER_HOST based configuration   unix:///var/run/docker.sock
desktop-linux *   Docker Desktop                            unix:///Users/outatimedev/.docker/run/docker.sock

so we get this error because we are running docker desktop and the socket is located in ~/.docker/run/docker.sock. to solve this issue, you need to create a symlink to the docker socket:

create-docker-socket-symlink
# you might need to use sudo
ln -s /Users/outatimedev/.docker/run/docker.sock /var/run/docker.sock

.actrc file

you can create a ~/.actrc file in your project directory to store default options for act:

~/.actrc
--container-architecture linux/amd64

basic usage

run all actions:

run-all-actions
act

run a specific job:

run-specific-job
act -j <job_name>

use a specific event:

use-specific-event
act push

common use cases

  1. testing workflow changes:
test-workflow-changes
act -W .github/workflows/my-workflow.yml
  1. debugging a specific job:
debug-specific-job
act -j build -s GITHUB_TOKEN=<your_token>
  1. using custom docker image:
use-custom-docker-image
act -P ubuntu-latest=myuser/myimage:latest

potential pitfalls

  1. secrets: act doesn’t have access to your github secrets by default. use -s flag to pass secrets:
pass-secrets
act -s MY_SECRET=value

  1. resource limitations: some actions might require more resources than your local machine can provide.

  2. platform-specific actions: actions designed for specific os or architectures might not work locally.

conclusion

act is a powerful tool for local github actions development. it speeds up testing, simplifies debugging, and reduces dependency on github’s infrastructure. remember to keep your local environment as close to github’s as possible for accurate results.

key takeaways: