Skip to main content

Run github action locally using act

· 5 min read

Yeah, being doing the CI/CD implementations via github workflow lately and I am also trapped in the process of making commits to trigger the workflows or better still making empty commits, haha.

Well, you can say why don't you just use Jenkins, CircleCi, and Gitlab CI? I think this all boils down to what your org uses, I think there is no need to go the Jenkins way when my org uses github and github has the workflow to implement CI/CD.

github spammy actions

Now, looking at the above screenshot, I am very sure that's how your Actions page looks like too, but what if you could test the workflows you write locally before pushing it to github?

That way, you can limit the spammy look of failed builds on your Actions page.

Thanks to nektos for building and open sourcing Act.

Act is a golang tool that allows you to run your GitHub Actions locally 🚀, making the feedback process really quick for your tests.

Now let's jump into how to use this

Firstly, you will need to install docker, Act depends fully on it,

Done with that? now let's install act on our environment, I use macOS, so I will be installing it using brew, you can also install it on Linux using brew

brew install act

You can as well check the installation guide for other installation methods.

Time to run your github actions locally

Done with the installation of act ? it's time to run act.

Navigate into your project folder where you have your github workflow files and run the following command on your terminal.


That should spin things up and then display some outputs where you are asked to select the image you would like to use with act.

You will only see this once because it's your first time running `act.

You can choose the medium image size, it is sufficient and okay, way better than micro option, after selecting the image size and hitting the enter button.

It will run and spin up the ~/.actrc file that contains the image configurations, you can always change this manually anytime.

So Immediately after selecting the image size, act also auto-detects any workflow file in your .github/workflow folder and it will proceed with spinning up a docker container and run the actions workflows in it.

act image selection

Whenever the github actions workflow is done, the docker container gets discarded, but there is a way around that

In situations where you need to get the results/feedback of your workflow actions which are probably passed to HTML, json, or XML files as output, you won't be able to access it because the docker container gets discarded.

But act has a subcommand to help with that, which makes your docker containers reusable.

hence you can enter the docker container to view the output of your action or copy it into your local system, whichever one is okay with you.

Here is the parameter to achieve that

act --reuse

Saving time on running your actions locally

You can also save time running these actions workflows, sure you don't want to wait all day for the local option you've chosen to take so much of your time, so if you will be running npm install or yarn install in your workflow and by chance already have a node_modules folder in your project root.

act can feed on the node_modules folder and speed/skip the dependencies installation process, here is the command to get that done

act -b
skip dependencies in workflow actions

Yeah, there is more, what about the github action secrets? will your workflows with the secrets run locally? Yes they will

Passing secrets into your local github actions workflow

Passing github workflow secrets can be done in various ways, you can enter them manually using the -s parameter.

act -s GITHUB_TOKEN=[insert token]

Alternatively, use the --secret-file parameter too, that way you can pass more workflow secrets along with your workflow, just create and open my.secrets file in your project root folder.

touch my.secrets
open my.secrets

Then add your action secrets into the file in the following formats


then run the file with the secret-file parameter

act --secret-file my.secrets

And that's all, there are more act options you can play with to speed up your devsecops or DevOps with github action by testing workflows locally.