act for running GitHub Actions locally

act is a tool offered by Nektos which provides a handy way to run GitHub Actions locally using Docker. act provides a quick way to validate your changes on the CI locally, without committing/pushing your changes to the workflows to trigger and validate the same. It leads to fast feedback and its compatibility as a local task runner, to validate all our CI jobs makes it a handy tool.

act can be set up locally with Homebrew, Chocolatey or even a simple BASH script. To set it up using the BASH script, just push the following command on your terminal:

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

Using Homebrew you can set it up via: brew install act.

The next step is to define the custom image that we can use to run our actions locally. act provides a micro, medium and larger Docker image for Ubuntu GitHub runner. act does not support Windows and macOS images yet.

While running act for the first time, we can define the image that we would like to utilize for our local CI runs. The configuration is saved inside the ~/.actrc file.

In a GitHub repository, while running act for the first time, it will find the ./.github/workflows and all the workflows present. To checkout the jobs listed as part of the GitHub Actions CI, push the following command:

act -l

It will list all the jobs and you can pick up the particular jobs you wish to run. If you are looking to run a particular job, push in the following command:

act -j <JOB_NAME>

To run the job in dry run, push in the following command:

act -n

To run the job with verbose logging, push in the following command:

act -v

To reuse the containers in act to maintain state, push in the following command:

act -j <JOB_NAME> --bind --reuse

It is recommended to comment out GitHub specific events like github.repository or github.event.head_commit.message. If you are using environment variables, in your action, it is recommended to have a my.secrets file and supply these environment variables to the act by pushing the following command:

act --secret-file my.secrets

If the environment variables are supplied via .env file, use the following command:

act --env-file my.env