nektos/act: run GitHub Actions workflows on your own machine

The problem act solves: testing workflow YAML without a push

A change to a file under .github/workflows/ normally only produces feedback after a commit and a push, because the workflow runs on GitHub's infrastructure. That loop is slow when you are editing YAML, and it is slower still when the workflow builds one of your own actions from source. The README puts the motivation plainly: rather than committing and pushing every time you want to test changes to your workflow files, you can use act to run the actions locally. The second stated reason is that act can serve as a local task runner, replacing a Makefile with the GitHub Actions you already define in .github/workflows/. That second use is the more interesting one, because it means the workflow file becomes the single source of truth for both CI and local execution. The audience is developers who already write GitHub Actions and want to run them on a laptop or workstation. The README also points to a VS Code extension, GitHub Local Actions, which runs act from inside the editor. act does not remove the need for CI. It shortens the edit-run loop before the commit.

How act resolves and executes a workflow

The README describes the execution model in a few sentences. act reads your GitHub Actions from .github/workflows/ and determines the set of actions that need to run. It then uses the Docker API to pull or build the images defined in the workflow files, and determines the execution path from the dependencies declared between jobs. Once it has that path, it uses the Docker API again to run a container for each action based on the images prepared earlier. Environment variables and the filesystem are configured to match what GitHub provides. The dependency graph is the part that matters most: act is not running jobs one after another blindly, it is reading the needs relationships and scheduling accordingly. The Docker API is the only execution backend described in the README, which is why a working Docker daemon is a precondition rather than an option. The README does not describe how act handles matrix expansion, service containers, or caching beyond the general statement about images and dependencies; the user guide at nektosact.com is where that detail is said to live.

Installing act and running a workflow for the first time

The README does not include a curl-pipe install line, but the repository ships an install.sh generated for releases, and the user guide is the documented place for installation instructions. If you build from source, the README gives the exact steps: Go 1.20 or newer, clone the repository, run the tests, then build and install. The Makefile shows what make install does: it builds with go build into dist/local/act and copies the binary to $(PREFIX)/bin/act, with PREFIX defaulting to /usr/local.

git clone [email protected]:nektos/act.git
cd act
make test
make install

After that, act --version should print the version derived from git describe, since the build passes -X main.version=$(VERSION).

For a first real run, act with no arguments reads .github/workflows/ in the current directory. The README links a sample repository, cplee/github-actions-demo, for seeing it in action, so cloning that and running act inside it is the shortest path to a working example.

cd github-actions-demo
act

What you should see is act listing the jobs it found, pulling or building the required images through the Docker API, and then streaming each container's output. If the workflow needs a token or a secret, act reads them from flags or environment files rather than from GitHub; the README does not enumerate those flags, so check the user guide before assuming a variable is passed through automatically.

Where act diverges from a GitHub-hosted runner

The README claims that environment variables and the filesystem are configured to match what GitHub provides. Treat that as a design goal, not a guarantee. act runs containers through your local Docker daemon, so the kernel, the available CPU and memory, and the image layers are whatever your machine has. A GitHub-hosted runner is a specific VM image maintained by GitHub with a fixed set of preinstalled tools. If your workflow depends on a tool that happens to be present on the hosted image but not in the container act builds, the job will pass on GitHub and fail locally, or the reverse. The README does not document rollback, caching behaviour, or how service containers are handled, and it does not promise parity for every runner feature. The honest framing is that act is a fast approximation. It is good at catching YAML mistakes, bad shell quoting, and broken job dependencies. It is not a substitute for a final run on GitHub before merge, and it is the wrong tool if your workflow depends on GitHub-specific services that have no local equivalent.

Alternatives, and how their approach differs

The most direct alternative is to push a branch and let GitHub run the workflow, which is exact by definition and costs a round trip. act trades that exactness for speed. A second option is a general local CI runner, such as running the same build steps through Make or a shell script; that avoids Docker entirely but abandons the workflow file as the source of truth, which is the specific thing act is trying to preserve. A third option is a hosted CI system other than GitHub Actions, which changes the workflow syntax and the execution environment rather than reproducing either. Among tools that execute GitHub Actions locally, act's distinguishing choice is that it drives the Docker API directly and reuses the images named in the workflow, rather than reimplementing the runner protocol. That is also its main constraint: no Docker daemon, no act.

Maintenance, licence, and what upgrading costs

act is MIT licensed, so you can use, modify, and redistribute it with the licence text, and there is no copyleft obligation on your workflows. The repository is not archived. The last push was on 2026-06-01, which matches the v0.2.89 release on the same date; the two prior releases, v0.2.88 and v0.2.87, landed on 2026-05-01 and 2026-04-01. That is a roughly monthly release cadence over the three most recent versions, and the version numbers are still in the 0.2.x range, so expect minor releases to carry fixes and occasional behaviour changes rather than a frozen interface. Upgrading means replacing a single binary; if you installed it via make install, the same command rebuilds and copies it to $(PREFIX)/bin/act. The cost of upgrading is not the binary, it is rechecking the workflows you rely on, because a change in how act prepares images or resolves dependencies can surface as a job that behaves differently than it did before. The README does not document a rollback procedure, so keeping the previous binary around is a decision you have to make yourself.

Editorial conclusion

Adopt act if you iterate on .github/workflows files or want a local task runner built from actions you already maintain, and if you accept that your host must run Docker and that GitHub-hosted runner images differ from local containers. Skip it if your workflows depend on GitHub-only features, on the hosted cache service, or on exact parity with the runner image. Before trusting it, run the workflow once with act and compare the environment variables and filesystem paths it prints against what the same job logs on GitHub, then check whether the actions you depend on are published as Docker images or must be built from source.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes