Skip to content
Get packs

Guide · Open source

How to use act: run GitHub Actions locally

Updated · written with AI from the project's own documentation and checked against our catalogue data

act is an open-source command-line tool from nektos that reads the GitHub Actions workflow files in your repository and runs them on your own machine instead of on GitHub. This guide explains what it does, what you need before installing it, and how to use it to test workflow changes faster. By the end you will understand how act runs jobs in Docker containers and where its behaviour differs from GitHub's hosted runners.

actnektos/act · ★ 72.5k · MIT

Quick start

  1. 1Install Docker. Make sure Docker is installed and running on your machine, since act uses the Docker API to run containers.
  2. 2Get act. Install act with a package manager, or clone the repository and build it from source.
  3. 3Build from source if needed. Install the Go version listed in go.mod, clone the repo, then run make install.
  4. 4Open your repository. Change into a project that has GitHub Actions workflow files under .github/workflows/.
  5. 5Run your workflows. Run act to read your workflow files and execute the jobs in containers on your machine.
  6. 6Iterate on your workflow. Edit the files in .github/workflows/ and run act again instead of committing and pushing each change.

What act does and why people use it

act reads workflow files from .github/workflows/ and runs them locally rather than on GitHub. The README gives two main reasons: fast feedback, because you do not have to commit and push every time you change a workflow, and a local task runner, because you can reuse your workflow definitions in place of a Makefile.

What you need before you install act

act uses the Docker API to pull or build the images your workflows need and to run each job in a container. Docker must be installed and running on your machine. The README says the tool is aimed at people comfortable running Docker locally.

  • Docker, required because act runs containers through the Docker API
  • Go, only if you build act from source; the README lists the version in go.mod, currently 1.26.0

Install act

The source lists a package-manager install method. To build from source, the README gives these steps: clone the repository, then build and install it with make. Running the unit tests needs Docker, while the fast tests do not.

  • Clone the repository with git clone git@github.com:nektos/act.git
  • Build and install from the repository directory with make install
  • Optionally run unit tests with make test (requires Docker) or make test-fast (no Docker needed)
git clone git@github.com:nektos/act.git make install

How act runs a workflow

When you run act, it reads the workflows in .github/workflows/ and works out which jobs need to run. It pulls or builds the images those workflows define, determines the execution order from the job dependencies, and then starts a container for each job. Environment variables and the filesystem layout are set to match what GitHub provides.

Know the limits before you rely on act

act aims to match GitHub's environment variables and filesystem, but the README does not claim it is an exact copy of GitHub's hosted runners. The README also does not describe how workflows that depend on GitHub-hosted services behave locally, so check those workflows carefully.

  • Expect close, not identical, behaviour to GitHub-hosted runners
  • Workflows that rely on GitHub-hosted services need extra checking
  • For help, the README points to the project discussions page

What people use it for

  • Testing changes to a .github/workflows/ file before pushing them to GitHub
  • Reusing existing GitHub Actions definitions as a local task runner in place of a Makefile
  • Getting faster feedback on workflow edits than a commit-and-push cycle gives

Frequently asked questions

Is act free to use?

act is released under the MIT licence, according to the project listing. The MIT licence is a permissive open-source licence, so check its terms if you plan to redistribute or modify the code.

What do I need to run act?

You need Docker, because act uses the Docker API to run containers. You also need Go only if you build act from source, and the project lists the Go version in go.mod.

How do I install act?

The project lists a package-manager install method. To build from source, clone the repository with git clone and run make install.

Does act behave exactly like GitHub-hosted runners?

No. The README says act matches environment variables and filesystem layout but does not claim full equivalence with GitHub's hosted runners. Test important workflows before relying on them.

Can act run workflows that use GitHub-hosted services?

The README does not describe how workflows that depend on GitHub-hosted services behave locally, so you should verify those workflows yourself.

What are the alternatives to act?

The project lists comparable projects including Gitlab Runner, Woodpecker CI, Drone and Dagger. These are different tools, so pick based on your CI setup and whether you need local runs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

act suits developers who edit GitHub Actions workflows and want faster feedback, and teams who want to reuse those definitions as a local task runner, provided they already run Docker. If you have no Docker, need an exact copy of GitHub's hosted runners, or depend on GitHub-hosted services, look at other tools such as the comparable projects listed above.

Install options & downloads