Nektos Act is a tool that enables developers to test their GitHub Action Workflows on their local development machine. This can be a significant productivity enhancement because you no longer need to check workflows into GitHub to test them.

Getting Started

Please see the comprehensive explainer and guide on Nektos on their GitHub page. I’ll be focusing on how you can quickly get up and running and testing your GitHub Actions locally.

1. Install Act

With Macos Homebrew:

brew install act

On any *nix device:

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

Verify act is installed by running:

act --version

Output:

act version 0.2.20

2. Testing

act will evaluate the GitHub Action workflows in your current directory. It’s a good idea to navigate, in a terminal window, to the root directory of a GitHub repo that contains the workflow you would like to test/run locally.

List the GitHub Action workflows you can trigger with your default event:

act -l

The example output (for my website’s lone GitHub Action workflow):

ID     Stage  Name   
build  0      build  

List the GitHub Action workflows that are triggered by the pull request event.

act push -l

Example output, for Iris:

ID     Stage  Name   
build  0      build   

Just like GitHub does for you, you can use act to trigger one or more workflows based on a GitHub event, like a new commit, pull request, etc.

For example, to mimic a GitHub Pull Request Open event:

act pull_request

You can also run a specific job directly:

act -j name_of_job

Executing these commands will run one or more workflow jobs. The output (and result) of each job will be printed in the terminal window.

Note: the first time you run act, it may take a while. It downloads the Docker image that will execute your GitHub Action workflow locally.

Shortcoming

act has a shortcoming you should be aware of. It is useful for workflows that don’t need custom GitHub runner images, but if your workflow requires or specifies a custom image, act will ignore it and run your workflow on one of it’s own images.

Example:

name: Workflow Name

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

jobs:
  build:
    runs-on: my-image

You can attempt to define your own images for use with:

act -P <platform>=<docker-image>

Example:

act -P my-image=docker.image.com/image/my-image:1.0.0

Using your own images with act is worth more investigation, but I’m going to end it here.