act: Run GitHub Actions Workflows Locally

What act is

act is a command-line tool from the nektos organisation that runs GitHub Actions workflows on your own machine. Its README sums the idea up in one line, "Think globally, act locally", and gives two reasons to use it. The first is fast feedback: instead of committing and pushing every time you change something under .github/workflows/, or every time you touch an action embedded in your repository, you run the workflow locally and see what happens. The second is using it as a local task runner. The author says they like make but dislike repeating themselves, so the workflows already defined for CI can stand in for a Makefile during day-to-day development.

The tool is written in Go, licensed under MIT and distributed as a single binary for macOS, Linux and Windows. It is aimed at anyone who maintains GitHub Actions workflows: application developers tired of the push-and-wait loop, platform engineers who own shared workflows and composite actions, and authors of reusable actions who want to try changes before publishing a tag. It is not a replacement for GitHub's hosted runners and does not try to be one. It is a way to execute the same YAML with containers you control, so that most mistakes surface in seconds rather than after a round trip through CI.

A small ecosystem has grown around it. The README points to a Visual Studio Code extension called GitHub Local Actions, which uses act under the hood so you can run and test workflows without leaving the editor, and the documentation describes a gh extension that lets you call it as gh act.

How it works

From workflow files to containers

When you run act, it reads the workflows in .github/workflows/ and works out which actions need to run for the event you asked for. It then uses the Docker API to pull or build the images the workflow files call for, and determines the execution path from the dependencies between jobs (the needs relationships). Once it has that path, it uses the Docker API again to run a container for each action, based on the images prepared earlier. The README stresses that environment variables and the filesystem are configured to match what GitHub provides, so steps that read GITHUB_* variables or expect the usual workspace layout behave much as they would on a hosted runner.

Runner images

GitHub's hosted runners are full virtual machines with a large set of preinstalled tools. act has to approximate them with containers, so it maps each runs-on label to a Docker image. The documentation lists three sizes per Ubuntu label. For ubuntu-latest, the micro image is node:16-buster-slim, the medium image is catthehacker/ubuntu:act-latest and the large image is catthehacker/ubuntu:full-latest; similar mappings exist for ubuntu-22.04, ubuntu-20.04 and ubuntu-18.04. The catthehacker images are maintained in a separate repository, and the large ones are described as filesystem dumps of the runners GitHub provides.

The docs are blunt that the default images are intentionally incomplete. They do not contain every tool GitHub ships on its runners, and some software may not work even when installed, because GitHub's runners are fully virtualised machines while act uses Docker containers. The example given is systemd, which Docker does not support running. If you need something closer to the real environment, you can point a platform at a different image with -P, including the nektos/act-environments-ubuntu:18.04 image built from GitHub's own Packer files, which the documentation warns is larger than 18 GB.

Running on the host instead of in Docker

Not every job needs container isolation. The runners guide shows that if you are on Windows or macOS and want to run jobs for that platform, you can opt out of Docker for a label and run the steps directly on the host by mapping it to -self-hosted, for example act -P macos-latest=-self-hosted. In that mode you do not need Docker installed or running at all. It is a useful escape hatch for macOS or Windows build steps that no Linux container can reproduce, at the cost of running workflow commands with your own user's access to the machine.

Key features

• Event selection. Run act with an event name such as push, pull_request or schedule; with no event it defaults to push. act -l lists the workflows that a given event would trigger.
• Event payload files. Workflows that read github.event can be fed a JSON file with -e, for example to supply head_ref and base_ref for a simulated pull request or a ref for a tag push.
• Workflow and job filtering. -W limits the run to a directory or a single workflow file, and -j runs only the jobs with a given ID.
• Secrets and variables. Secrets come from -s NAME=value, from the environment, from a secure prompt when you pass -s NAME on its own, or from a --secret-file in dotenv format. Repository variables work the same way with --var and --var-file.
• Workflow dispatch inputs. Manually triggered workflows can receive inputs with --input, --input-file or an inputs object in the event JSON.
• Matrix subsets. --matrix node:8 runs only the matrix combinations that include that value. It filters existing combinations and cannot add new ones, and exclude in the workflow still wins.
• Offline mode. --action-offline-mode stops act from re-pulling images and actions it already has, so it keeps working on a flaky connection or without network access after a first online run, and helps with registry rate limits.
• Local artifacts. With --artifact-server-path set, act starts an artifact server so actions/upload-artifact and actions/download-artifact (v3 and v4) can pass files between jobs in the same run.
• A config file. Default flags can live in .actrc files, one argument per line, read from the XDG location, the home directory and the invocation directory before command-line arguments are applied.
• Custom engines and GitHub Enterprise. Setting DOCKER_HOST points act at another Docker-API-compatible socket, including a remote engine over SSH, and --github-instance lets it resolve actions from a GitHub Enterprise Server host.

Getting started

The installation guide states the main prerequisite up front: act depends on Docker, specifically the Docker Engine API, to run workflows in containers. On macOS and Windows that means Docker Desktop; on Linux, Docker Engine. Homebrew covers macOS and Linux:

brew install act

On Windows, WinGet is one of several package managers listed alongside Chocolatey and Scoop:

winget install nektos.act

If you already use the GitHub CLI, you can install act as an extension and call it through gh:

gh extension install https://github.com/nektos/gh-act
gh act push
gh act -l pull_request

There is also a bash install script that downloads a released binary. The docs note that it cannot install unreleased versions, and, as with any piped script, it is worth reading before you run it as root:

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Prebuilt archives for macOS (Apple Silicon and Intel), several Linux architectures and Windows are attached to every GitHub release. Arch, COPR, Nix, MacPorts and others package it too.

Once installed, run it from the root of a repository that has workflows. A plain act runs every workflow triggered by push; naming an event or listing first is often more useful:

act -l pull_request
act pull_request
act -j 'test'

If a workflow needs a token, the usage guide suggests reusing the GitHub CLI's credentials rather than pasting a personal access token on the command line:

act -s GITHUB_TOKEN="$(gh auth token)"

To build from source, the README asks for the Go version named in go.mod (1.26.0 at the time of writing), then make test for the unit tests (which require Docker), make test-fast for tests that do not, and make install to build and install.

Use cases

Iterating on workflow YAML

The most common use is the one the README leads with: editing a workflow and checking that it parses, that expressions evaluate the way you expect and that the steps run in the right order, without pushing a string of "fix CI" commits. Listing jobs with -l, running a single job with -j and narrowing a matrix with --matrix keep each iteration short.

Developing composite and Docker actions

Authors of actions that live in the same repository as their workflows can change the action and run a workflow that uses it immediately. The support matrix in the documentation marks docker, node12, node16 and composite action types as supported, along with action inputs and outputs.

A task runner shared with CI

Teams that already describe linting, testing and building in workflow files can run those same jobs locally instead of maintaining a parallel set of shell scripts or make targets. The docs show how to keep steps that only make sense in CI, such as posting to Slack or bumping a version, out of local runs: act sets an ACT environment variable, so a step can use if: ${{ !env.ACT }}. Whole jobs can be skipped with a custom event property, because the env context is not available in job-level if conditions.

Debugging on a remote or alternative engine

Because DOCKER_HOST is respected, the same workflows can run against a beefier remote machine over SSH, or against Podman's socket. Neither is the default path, which matters for the caveats below.

How it compares

The obvious comparison is with simply pushing to GitHub and letting hosted runners execute the workflow. That remains the reference environment: it has the complete runner image, real GITHUB_TOKEN scoping, OpenID Connect, deployment environments, concurrency groups and step summaries, none of which act fully reproduces. What act offers instead is speed and control, with feedback in the time it takes to start a container and no CI minutes consumed. In practice many teams use both: act to get a workflow mostly right, then a push to confirm.

The other point of comparison is a self-hosted GitHub runner. A self-hosted runner is registered with GitHub and receives jobs from it; act never talks to GitHub's job queue and runs only what you start locally. That makes act simpler to set up for experimentation, but it is not a way to run production CI on your own hardware. Plain task runners such as make, which the README mentions, are the third reference point: more predictable and dependency-free, but a second definition of the same steps that your workflows already contain.

Things to know before adopting

• Docker is effectively required. Container jobs need the Docker Engine API. The installation guide says act is not currently supported with Podman or other container backends; it might work through DOCKER_HOST, but that is not guaranteed.
• Docker contexts are ignored. The active docker context is not respected, and the maintainers have listed fixing that as something they are not going to work on. The documented workaround is to export DOCKER_HOST (and DOCKER_CERT_PATH where client certificates are needed) from the context yourself.
• Default images are not GitHub's images. Missing tools are the most common source of "works on GitHub, fails in act" problems. Expect to choose a medium or large image, or your own, with -P, and expect large downloads for the full images.
• Images are pulled on every run by default. The --pull flag defaults to true because of breakage with older default images. Use --pull=false or offline mode if you want to use a locally built image without re-pulling.
• Several workflow features are ignored. The unsupported-functionality page lists concurrency, run-name, step summaries, problem matchers, annotations, job.permissions, job.timeout-minutes, job.continue-on-error and job.environment (including environment-scoped secrets) as ignored, and notes that the github context is incomplete and no OIDC URL is defined. Cancelling run steps is not implemented either.
• Support for some keys is partial. The support matrix, itself marked as a work in progress, notes that matrix resolution does not match GitHub's in every case, that fail-fast will not actually fail fast, that max-parallel support is incomplete and that services containers are not supported.
• Secrets can leak into shell history. The usage guide warns that typing secrets on the command line may store them in plain text in your shell history, and recommends the secure prompt that -s NAME provides, or a secrets file kept out of version control.
• Artifacts need opting in. The artifact server does not start automatically, and while enabled its runtime variables are visible to run steps, which is not how GitHub's runner behaves. Downloading artifacts from another run, workflow or repository is not supported.
• Node must be on the PATH for JavaScript actions. GitHub's runner ships its own Node for JavaScript actions; with act, the container (or your host, in self-hosted mode) must provide it.
• Pre-1.0 versioning. Releases are still numbered 0.2.x, so read release notes when upgrading rather than assuming strict compatibility guarantees.

Project activity

As of November 2026 the nektos/act repository has about 72,500 stars on GitHub and roughly 2,100 forks. It was created in January 2019, is written in Go and is licensed under MIT. The most recent release at the time of writing is v0.2.97, published on 4 November 2026, and the default branch was pushed to the same day, so the project is under steady maintenance. Questions go to GitHub Discussions, and the contributing guide in the repository explains how to send changes.

The source is at github.com/nektos/act, and the user guide, generated from the nektos/act-docs repository, is published at nektosact.com.

[![Featured on TechLogHub](https://techloghub.com/badge-neutral.svg)](https://techloghub.com/open-source/nektos-act?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)