act - Run Github action locally

What is act and what problem does it solve?

When building pipelines using GitHub Actions, testing code inside our codebase locally is possible. However, as we add more steps to our workflows and push changes to GitHub, we may encounter issues that require repeated iterations of pushing fixes until everything works correctly. This process can be time-consuming and inefficient.

To enable faster feedback loops, we can use act tool that allows you to run GitHub Actions locally without needing to push your commits to GitHub.

act leverages the Docker API to pull or build the necessary images as defined in your workflow files. It determines the execution path based on the dependencies specified in the workflows.

act is written in Go and is open-source.

How to Install act Locally

Prerequisites

• Docker Desktop

Installation Commands

For Windows:

# Using Chocolatey
choco install act-cli

or

# Using Winget
winget install nektos.act

For macOS:

brew install act

For Linux:

nix run nixpkgs#act

Useful Commands in act

Once you navigate to the directory containing your GitHub workflow files, you can use the following commands. Ensure Docker is up and running before proceeding.

Run the Workflow

Below is a sample GitHub action file saved locally in .github/workflows/hello-world.yaml

name: hello-world
on: push
jobs:
  hello-world:
    runs-on: ubuntu-latest
    steps:
      - name: Say hi
        run: echo "hi world"

To execute the workflow file:

act

For detailed output, pass the -v or --verbose flag:

act -v

List Jobs

To list all workflow files, along with their workflows and job names:

act -l

Example output:

# Output of act -l
Stage  Job ID       Job name     Workflow name  Workflow file     Events
0      hello-world  hello-world  hello-world    hello-world.yaml  push  

Run a Specific Job

To run a specific job, use the -j flag followed by the Job ID:

act -j hello-world

Run a Specific Workflow File

If you have multiple workflow files and want to run a specific one, use the -W (uppercase) or --workflows flag with the relative path to the workflow file:

act -W ".github/workflows/hello-world.yaml"

Reuse the Same Container

When testing a workflow to fix an issue, you can reuse the same container by passing the -r flag:

act -j hello-world -r

Running with Secrets

To use secrets in your workflows, create a .secrets file, e.g.:

SECRET_VALUE="My secret"

Example workflow file:

name: Run with secrets

on:
  push

jobs:
  secret-job:
    runs-on: ubuntu-latest
    steps:
      - name: Running secret
        run: echo "Sssh the value is ${{ secrets.SECRET_VALUE }}"

Run the workflow with act:

act -j secret-job

Output:

Sssh the value is ***

Similar to GitHub Actions, the secret value is masked in the output.

.actrc File

If you are using an Apple M-series Mac, you might encounter the following warning:

WARN  ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠  

To resolve this, you can create a .actrc file in your home directory to specify commonly used arguments.

Using VS Code:

code ~/.actrc

Add the following content to the file:

--container-architecture linux/amd64
--pull=false

Conclusion

act is a powerful and efficient tool for testing GitHub Actions workflows locally. By enabling faster feedback loops and reducing the need for repeated pushes to GitHub, it streamlines the development process and saves valuable time. Whether you’re debugging workflows, testing secrets, or running specific jobs, act provides a versatile and user-friendly solution for developers.