Tool Spotlight: `act` (for GitHub Actions)

How act Works

act is an open-source command-line tool that runs GitHub Actions workflows locally. It reads your .github/workflows/*.yaml files and uses Docker to spin up containers that closely mimic the GitHub-hosted runners.

The execution flow:

1. You run act push (simulating a push event).
2. act parses your workflow YAML and identifies which jobs should run for a push event.
3. It pulls a Docker image — by default catthehacker/ubuntu:act-latest — that contains the same pre-installed tools as the standard ubuntu-latest GitHub runner (Node.js, Python, Go, Docker CLI, etc.).
4. It mounts your project directory into that container.
5. It executes each step defined in your YAML, in order, inside the container.
6. Output streams to your terminal in real time, color-coded by job.

The result: you see exactly what GitHub Actions would see, without pushing a single commit.

act installs via Homebrew on macOS, a shell installer script on Linux, or Chocolatey on Windows — all standard package-manager installs.

Common act Commands

act supports a small set of core operations: listing every job across all workflows without running anything, running all jobs for the default push event, running one named job, targeting a specific workflow file, and passing secrets in either individually or from a file. You can also override the default Docker image with a smaller one for faster local runs.

Handling Secrets Safely

Never hardcode secrets in your workflow files. When running locally with act, secrets go in a .secrets file in your project root (immediately added to .gitignore) and are passed in via a flag pointing at that file, rather than embedded anywhere in the workflow or committed to the repo.

Limitations of act

act is powerful but not a perfect replica of GitHub's infrastructure:

• OS-level differences: GitHub runners are full virtual machines. act uses Docker containers. Features that require a real kernel — systemd, certain iptables rules, hardware-level access — will not work inside a container.
• GitHub-specific APIs: Actions that call the GitHub API (creating releases, posting PR comments, updating check runs) require real GitHub credentials and a real repository context. These often need to be mocked or skipped during local runs.
• Resource constraints: Running a matrix strategy with 20 parallel jobs on your laptop will exhaust CPU and memory. act runs jobs sequentially by default when resources are limited.
• Proprietary actions: Some GitHub Marketplace actions have dependencies that assume the full GitHub runner environment and may behave differently in act's containers.

Despite these limitations, act eliminates the most common class of CI debugging pain: syntax errors, script failures, environment variable issues, and dependency problems. For 80% of CI debugging scenarios, it is the right tool.

Key Point: act is the right tool for debugging GitHub Actions locally, but it works best for logic and script errors. For GitHub API integrations or OS-level features, you still need the real runner — but those cases are rare compared to the everyday debugging act handles.