act: Run GitHub Actions Locally

Understanding act's Local Workflow Execution

act is a command-line tool that reads the workflow files in a repo's .github/workflows/ folder and runs the actions locally instead of on GitHub's servers. It works out which jobs need to run based on their dependencies, calls the Docker API to fetch or assemble the images those jobs specify, then runs each job in its own container with environment variables and a filesystem layout set to mirror GitHub's own setup.

Core Capabilities of act

• ✓Reads workflow files straight from .github/workflows/ and works out the execution order from job dependencies before running anything.
• ✓Calls the Docker API to fetch or assemble the container images a workflow references, rather than requiring you to prepare images by hand.
• ✓Runs each action inside its own container, with environment variables and a filesystem layout set to mirror GitHub's own setup.
• ✓Can stand in for a Makefile: workflows already written for GitHub Actions become the same commands you run locally, so logic doesn't live in two places.
• ✓Has a companion VS Code extension, GitHub Local Actions, built by a separate maintainer, for running and managing act without leaving the editor.
• ✓Ships as a Go project under the MIT license that you can build yourself with Go 1.20+ and make, if you'd rather not use a packaged release.

Practical Applications for act

• •Checking that a change to a workflow YAML file actually runs the way you expect before pushing it and waiting on GitHub's queue.
• •Replacing a project's Makefile with the same job definitions already written for CI, so there's one script to maintain instead of two.
• •Debugging a failing step by rerunning just that part of the workflow locally instead of re-triggering the whole pipeline on GitHub.
• •Running act from inside VS Code via the GitHub Local Actions extension when you'd rather not switch to a terminal.

Getting Started: Installing act

The only install path documented in the facts here is building from source: install Go 1.20 or newer, clone the repo with git clone [email protected]:nektos/act.git, run the unit tests with make test, then build and install with make install. The README also points to a separate user guide at nektosact.com for fuller documentation, so a packaged binary or package-manager command isn't clearly documented here; treat anything beyond the make install path as not covered by these facts.

Running Your GitHub Workflows Locally

Running act comes down to invoking it from a repo that has a .github/workflows/ directory. It reads those files, works out which jobs need to run, and calls the Docker API to fetch or assemble the images each job needs before executing them in containers. The README frames this around two specific use cases: fast feedback on workflow edits without a commit-and-push cycle, and using the same GitHub Actions definitions as a local task runner instead of a Makefile. In practice, that means running act right after editing a workflow file. Flags and command syntax beyond that entry point aren't part of the facts here; the README defers to the user guide at nektosact.com for the rest.

Alternative Approaches to Workflow Testing

Frequently Asked Questions about act

The problem it solves

Testing a GitHub Actions workflow normally means editing .github/workflows/*.yml, committing, pushing, and waiting for GitHub's runners to pick up the job, then repeating that loop for every typo or missing environment variable. act's README frames its reason for existing around cutting that specific loop: run the same workflow files against Docker on your own machine and see the result right away, or use those same files as your project's task runner instead of hand-writing a Makefile that duplicates the same commands.

Who should try it — and who should skip

Try act if you're actively editing .github/workflows/ files and are tired of the commit-push-wait cycle just to see whether a step runs, or if you want your CI job definitions to double as your local task runner instead of writing a separate Makefile. Skip it if your team rarely touches workflow files, or if you need hosted-runner parity beyond what's documented: the facts here describe environment variables and filesystem matching GitHub's setup, not a guarantee that every hosted-runner behavior is reproduced locally.

Related repositories