Github actions are taking a considerable part of the devops world. Developers find them super friendly for most use cases. Developing your flow can be much faster if you can run them locally. This article will show you how.

In our team we are running and developing multiple github actions daily. For a while, the only way to test them was to write a job or edit an existing one and push the change to github. This development flow is time consuming and discouraging.

A great open source project allows you to run your github yaml files locally with all the goodies of github actions. Let’s see how it is done.

How to Install Act

Act is an open source project that allows you to run your github flow locally. The first step is to install it. You have various ways to install it on various machines.

On Mac and linux you can use:

curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

If you are running Windows, download the latest release and add the binary into your PATH.

Other installation methods can be found here.

Once Act is installed, make sure you have Docker installed. Either install docker for mac or docker for windows.

After docker is installed, run it if it is not running and make sure the docker logo is stable.

Once docker and Act are installed, you are set to go.

How to run your github commands locally?

cd into your projects’ folder. In your folder you should have a .github/workflows folder with your github actions. If you don’t, create one and add a workflow yaml file.

Here’s an example for a valid yaml file:

If you’ve setup act, docker and the yml file you can now run the following command in your command line:

act

This will run a docker container, and run the github workflows in it.

How to pass secrets into your local github actions workflows?

in code snippet 1 in lines 13 and 31 we use secrets that are set in the repository’s settings. In order to make these available locally you have two options.

The first option is to use the -s parameter in the cli:

act -s ARTIFACTORY_AUTH_TOKEN=${ARTIFACTORY_AUTH_TOKEN} 

You can replace the secret’s name (ARTIFACTORY_AUTH_TOKEN with your secret’s name. Of course the value in this case is an existing variable on my machine which you can replace with any value.

You could run it without setting a value, in which case you will be prompted for a value.

You can also use a secrets file like this:

act --secret-file my.secrets 

How to save time running github actions locally?

Another important tip is to be able to run faster. In my case, I run a JavaScript project with npm or yarn. The step Install dependencies is using yarn in order to install my project’s dependencies. This might take a while.

We can speed this up by using the bind option:

act -s ARTIFACTORY_AUTH_TOKEN=${ARTIFACTORY_AUTH_TOKEN} -b

Notice the -b in the end of the above command. This will take the current project’s folder with its existing node_modules and thus save a lot of time with unneeded installation.

Note that this might cause changes to local files if you are doing any file manipulations during the workflow.

How to easily use Git in your local github actions workflows?

Using the command act on its own won’t be enough if you intend to run git commands (e.g. git fetch or git add .). The best way to make sure your workflows run exactly like in the repository itself is to use the act-environments docker image.

Our command will now look like this:

act -s ARTIFACTORY_AUTH_TOKEN=${ARTIFACTORY_AUTH_TOKEN} -b -P ubuntu-latest=nektos/act-environments-ubuntu:18.04

This will run our workflow in an environment similar to the one being run with the latest ubuntu in github actions.

This comes with git support and work out of the box for most workflows (worked for all of my workflows 🙂 ).

Summary

In this article we’ve learned how to run github actions locally using docker and the act project.

Act has many more options you can play with to make your devops with github actions a lot faster by working locally.

Thanks to Omer Dolev from Microsoft for the kind review.

Featured image was taken from https://lab.github.com/githubtraining/github-actions:-write-docker-container-actions