local GitHub Actions runner
Run the default workflow
act
List all available workflows
act -l
Run a specific workflow
act -W [.github/workflows/ci.yml]
Run a specific job
act -j [build]
Run with secrets from file
act --secret-file [.secrets]
Dry run to see what would be executed
act -n
Run with a specific platform image
act -P ubuntu-latest=catthehacker/ubuntu:act-latest
act [-W workflow] [-j job] [-e event] [--secret-file file] [options]
act allows you to run GitHub Actions workflows locally using Docker containers. It parses workflow YAML files and executes jobs in containers that simulate the GitHub Actions environment, enabling rapid iteration and debugging without pushing to GitHub.
The tool supports most GitHub Actions features including matrix builds, secrets, environment variables, and artifacts. It downloads and caches action repositories automatically.
-W file, --workflows file
Path to workflow file(s) (default: .github/workflows/)
-j job, --job job
Run a specific job
-e file, --eventpath file
Path to event JSON file
--secret-file file
Load secrets from file (KEY=VALUE format)
-s secret, --secret secret
Set a secret (KEY=VALUE)
--env-file file
Load environment variables from file
-P platform, --platform platform
Custom Docker image for platform (e.g., ubuntu-latest=catthehacker/ubuntu:act-latest)
--input input
Set a workflow input (KEY=VALUE)
--input-file file
Load workflow inputs from file
--matrix matrix
Select specific matrix configuration to run
--action-offline-mode
Don't pull images or fetch remote actions if already cached
-l, --list
List available workflows and jobs
-n, --dryrun
Show what would be run without executing
-r, --reuse
Reuse containers between runs
-b, --bind
Bind working directory instead of copying
--container-architecture arch
Container architecture (amd64, arm64)
~/.actrc
User-level default flags applied to every act invocation. Each line contains a single command-line flag (e.g.,
-P ubuntu-latest=catthehacker/ubuntu:act-latest).
.actrc
Project-level defaults, same format as the user-level file. Overrides user-level settings when present.
Not all GitHub Actions features are supported; some hosted runner features like service containers have limitations. Large workflow images can be slow to download initially. Some actions may behave differently locally than on GitHub. Docker must be running.
act was created by Casey Lee (nektos) and first released in 2019. It was developed to address the slow feedback loop of GitHub Actions by enabling local execution. The project quickly gained popularity in the CI/CD community.
dnf: sudo dnf install act
pacman: sudo pacman -S act
apk: sudo apk add act
zypper: sudo zypper install act
brew: brew install act
nix: nix profile install nixpkgs#act