Skip to main content
`Ctrl`+`K`

# 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