act: Run GitHub Actions Workflows Locally

act reads your .github/workflows files and runs the jobs locally inside Docker containers, letting you iterate without pushing commits.

Pushing a commit just to see if a workflow works is slow. act runs the same jobs on your machine so you can debug locally. This page covers usage and flags; for the Docker daemon and image errors act throws, see the CI errors module.

What it does

act parses your workflows, picks a Docker image per runner label, and executes each step in a container, simulating the push, pull_request, or any other event. It does not need GitHub; it reproduces the runner locally.

Common usage

Terminal

act -l                 # list all jobs and the events that trigger them
act                    # run the default (push) event
act pull_request       # simulate a pull_request event
act -j build           # run only the job named "build"
act push -n            # dry run: print the plan without executing

Options

Flag	What it does
-l, --list	List workflows and jobs without running them
-j, --job <id>	Run a single job by id
-n, --dryrun	Print the execution plan without running steps
-P, --platform <label=image>	Map a runner label to a Docker image
-s, --secret <NAME=val>	Provide a secret to the run
-W, --workflows <path>	Path to the workflow file or directory
--container-architecture <arch>	e.g. linux/amd64 on Apple Silicon

In CI

act is a local development tool, not something you run inside the CI runner itself. Use it to validate a workflow change before opening the PR, then let actionlint gate the PR. If you must run it in CI (nested Docker), you need a Docker-in-Docker setup.

Common errors in CI

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running? means Docker is not started or the socket is not mounted. Error: Please configure a default image ... appears the first time you run act. On Apple Silicon, image with reference ... was found but does not match the specified platform needs --container-architecture linux/amd64. See the CI errors module for full fixes.