DEV Community

Cover image for Local testing for GitHub Actions (on MacOS)
Andreas Frömer
Andreas Frömer

Posted on

Local testing for GitHub Actions (on MacOS)

The beginnings

Back in October 2018, when GitHub Actions were announced, things got pretty serious pretty fast. Everyone was jumping on the train and were replacing their old CI/CD integration with the new workflow GitHub now provided.

From my memory, the development of these workflows was a bit painful to say the least. You would have to add the changes to your workflow into your repository, push them and wait for the actions to complete.


If not, do it again until everything worked out. The only thing I had done this far was a simple checkout, running some tests and that was pretty much it. Nothing fancy going one there.

Recently I was reminded by @localheinz in a tweet that some of the actions for GitHub made a huge improvement.

Later today

Now one and a half years later having an actively used repository wit composer-unused, I decided to check things again and improve the workflows. But - the testing. There has to be a way to test your workflow on your local machine. Right?

Yes there is! nektos/act to the rescue.

This tool, written in Go, is pretty easy to install and navigate. I will give you a small overview how to install and run it on MacOS (other OS are also supported, see the documentation)

Get the tool running


nektos/act is using Docker to run your workflow on your machine. So first things first: setting up Docker using homebrew

$ brew install docker docker-machine
Enter fullscreen mode Exit fullscreen mode

You will also need to install a provider for Docker. For this example we are using Virtualbox. You can install it a Homebrew Cask recipe:

$ brew cask install virtualbox
-> password
Enter fullscreen mode Exit fullscreen mode

You might see the following message when installing Virtualbox:

virtual box security

You need to head over into the settings and accept the software installation from Oracle America Inc..

security setting

Next up, set up the default docker-machine with virtualbox driver and start it.

$ docker-machine create --driver virtualbox default
$ eval "$(docker-machine env default)"
Enter fullscreen mode Exit fullscreen mode

Install nektos/act

Installation instruction taken from the docs using homebrew:

$ brew install nektos/tap/act
Enter fullscreen mode Exit fullscreen mode

Run your workflow

To run your workflow on your machine, just navigate to your repository folder and run.

$ act
Enter fullscreen mode Exit fullscreen mode

This will run your default job inside your workflow. Thats it!

But wait! Thats all in the docs, so why this post?
Well - I encountered a problem along the way:

::error::ENOENT: no such file or directory, open '/opt/hostedtoolcache/'
Enter fullscreen mode Exit fullscreen mode

Solving the issue

The problem above has nothing to do with nektos/act itself. But rather with the default Docker image it uses. To solve this, you can run act -P <docker-image> to use another default image.

Turns out shivammathur/setup-php was the solution.

$ act -P ubuntu-latest=shivammathur/node:latest
Enter fullscreen mode Exit fullscreen mode

But typing this command all over again is - well - annoying.

To improve this, you can create a ~/.actrc file and put the command line arguments there so you only have to run act inside your repository.

// ~/.actrc
-P ubuntu-latest=shivammathur/node:latest
Enter fullscreen mode Exit fullscreen mode

Now everything is working as expected and I can improve my workflow to my needs while testing it locally on my machine first!


nektos/act is a little over a year old now, so there are still some problems with certain workflows and OS setups. I have only encountered the problem mentioned above.

If you encounter any other problem, don't hesitate and head over to the issue tracker of nektos/act and describe your problem. This way we all can improve this awesome tool even further!

Top comments (2)

nathanbeaumont profile image

I am unsure how to run act in the docker container? After starting the default docker machine, attempting to run github actions fails with "Skipping unsupported platform 'macos-latest'"

rgomezp profile image
Rodrigo Gomez Palacio

I am wondering the same