act — Run GitHub Actions Locally

What it is

act is a command-line tool that runs GitHub Actions workflows on your local machine. It uses Docker containers to simulate the GitHub Actions runner environment, letting you test and debug CI/CD pipelines without pushing commits to GitHub. You point act at your .github/workflows/ directory, and it executes the same steps that would run in GitHub's cloud runners.

This tool targets developers who iterate on CI/CD pipelines and want faster feedback than the push-wait-check cycle. Anyone maintaining complex GitHub Actions workflows with multiple jobs and conditional steps benefits from local testing.

How it saves time or tokens

Every push to test a CI change takes minutes of round-trip time: commit, push, wait for GitHub to schedule the runner, run the workflow, check results. act cuts this loop to seconds by running everything locally. For AI-assisted development where you generate and test workflow files iteratively, this acceleration means faster convergence on working pipelines.

How to use

1. Install act via Homebrew, Chocolatey, or download the binary
2. Ensure Docker is running on your machine
3. Run act in your repository root to execute the default push event workflow

Example

# Install
brew install act

# Run the default push event
act

# Run a specific event
act pull_request

# Run a specific job
act -j build

# List available workflows without running them
act -l

# Pass secrets
act -s GITHUB_TOKEN=your_token

# Use a specific image size (medium is default)
act -P ubuntu-latest=catthehacker/ubuntu:act-latest

Related on TokRepo

• DevOps tools — Explore CI/CD and deployment tools
• AI tools for automation — Browse automation workflows and tools

Common pitfalls

• act uses smaller Docker images by default that lack some tools present in GitHub's actual runners; use the full images for better compatibility
• Service containers (like PostgreSQL in CI) require Docker-in-Docker or host Docker socket mounting to work
• Some GitHub Actions features like caching and artifact upload have limited or no support in act