Act CLI: Run, Test & Debug GitHub Actions Workflows Locally

01. Ending the "commit -m 'try fixing CI 7'" Anti-Pattern

Every software engineer knows the pain of debugging a misconfigured environment variable, syntax flaw, or bash quotation mismatch in a CI pipeline: pushing a dummy commit, waiting 4 minutes in queue, watching it fail on line 42, and repeating the cycle dozens of times.

Traditional Remote CI Loop:

Edit YAML → Git Commit → Git Push → Wait in Runner Queue → Cloud Failure (3-6 mins per cycle). Wastes billable minutes, pollutes branch history.

Act Local Inner Loop:

Edit YAML → Run act -j lint → Instant Docker execution → Immediate stdout feedback (4-8 seconds). Zero git spam.

02. Installation & System Requirements

nektos/act requires a running Docker daemon (Docker Desktop, OrbStack, Podman, or native Linux dockerd).

Terminal Installation Commands

# macOS (Homebrew)
brew install act

# Windows (Winget or Chocolatey)
winget install nektos.act
# or: choco install act-cli

# Linux & WSL2 (Official Install Script)
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

03. Runner Platform Mapping & .actrc Configuration

By default, act maps ubuntu-latest to a lightweight Docker image. However, official GitHub runners contain hundreds of pre-installed CLI utilities (Docker, AWS CLI, Kubectl, Python, Go, Rust). For maximum fidelity, configure catthehacker/ubuntu:act-latest in a repository .actrc file:

Project Configuration: .actrc

# Map GitHub Actions runner tags to high-fidelity container images
-P ubuntu-latest=catthehacker/ubuntu:act-latest
-P ubuntu-24.04=catthehacker/ubuntu:act-24.04
-P ubuntu-22.04=catthehacker/ubuntu:act-22.04

# Reuse containers between steps to accelerate runtime
--reuse

# Pass host Docker daemon socket for jobs executing Docker commands
--container-daemon-socket /var/run/docker.sock

Image Tier	Docker Hub Image	Size	Included Utilities
Micro Image	node:16-buster-slim	~200 MB	Bare Node.js & git only
Medium (Default)	catthehacker/ubuntu:act-latest	~2.2 GB	Python, Node, Docker, Go, Make
Full Parity	catthehacker/ubuntu:full-latest	~18 GB	100% exact GitHub hosted replica

04. Essential Act Commands for Daily Development

Mastering the command syntax empowers developers to target specific jobs, inject local environment variables, and inspect the workflow DAG graph:

1. List All Discovered Workflows and Jobs:

act -l

2. Run a Single Job by Name (Bypassing Full Pipeline):

act -j test-unit

3. Simulate a Pull Request Event with Secrets:

act pull_request \
  --secret-file .secrets \
  --var ENVIRONMENT=staging \
  -s GITHUB_TOKEN="$(gh auth token)"

4. Dry-Run Execution (Validate Syntax & Actions Graph Without Running Steps):

act -n

05. Local Secrets Management & Security Hygiene

Never hardcode tokens into workflow files or commit them to source control. Create a local .secrets file in your repository root and ensure it is included in .gitignore:

.secrets (Strictly Git-Ignored)

AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
SNYK_AUTH_TOKEN=00000000-0000-0000-0000-000000000000
NPM_TOKEN=npm_mock_token_for_local_ci

When running act, supply --secret-file .secrets. The CLI securely injects these values into the container environment and scrubs them from terminal stdout logs.

Simulate Your Pipeline DAG Online

Before launching local Docker containers, paste your workflow YAML into CIPipelineGraph to inspect job dependencies and verify zero circular cycles.

Open In-Browser DAG Visualizer →

Act CLI: Run, Test & Debug GitHub Actions Locally Without Committing