How to Reproduce a Workflow Locally With act in GitHub Actions
act runs your workflow jobs in local Docker containers so you can reproduce a failure without pushing commits.
Install act, then run act <event> from the repo root. It reads .github/workflows, builds the job graph, and executes steps in containers that approximate the hosted runners.
Steps
- Install act (
brew install actor the install script). - Run
act push(or another event) at the repo root. - Pass secrets and a larger image when a job needs them.
Common commands
Terminal
# list the jobs act would run for the push event
act push -l
# run a single job by id
act -j build
# provide a secret and use a fuller ubuntu image
act -j build -s GITHUB_TOKEN=ghp_xxx \
-P ubuntu-latest=catthehacker/ubuntu:act-latestGotchas
- act emulates runners but is not identical;
services:, someuses:actions, and OIDC may differ. - The default micro image lacks many tools; map a
catthehacker/ubuntuimage with-P. - macOS and Windows runners cannot be reproduced; act runs Linux containers.
Related guides
How to Debug a Failing Step With bash Tracing in GitHub ActionsSee every command a GitHub Actions shell step runs, with variables expanded, by enabling bash xtrace via set…
How to SSH Into a Failed Runner With tmate in GitHub ActionsOpen an interactive SSH session into a live GitHub Actions runner using mxschmitt/action-tmate, so you can po…