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.

Hopefully.

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

Requirements

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

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

You might see the following message when installing Virtualbox:

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

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)"

Install nektos/act

Installation instruction taken from the docs using homebrew:

$ brew install nektos/tap/act

Run your workflow

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

$ act

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/linux.sh'

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

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

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

Disclaimer

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!