Gem cidevops

act

Run your GitHub Actions workflows locally in Docker.

Would you recommend act?

No votes yet. Tried it? Be the first to say.

One vote per person. No account needed.

Overview

act reads .github/workflows and runs jobs in containers on your machine, so you can debug CI without a push-and-wait loop.

Instead of

"fix ci" commit after "fix ci" commit

Reach for it when

You are iterating on a GitHub Actions workflow.

Key features

  • Run workflows locally

    Reads .github/workflows and runs jobs in Docker containers on your machine.

  • Choose the event

    act push, act pull_request, act workflow_dispatch, with optional event payload files.

  • Target jobs

    -j build runs a single job; -l lists what would run.

  • Secrets and variables

    Pass them with -s NAME=value, --secret-file or --var.

  • Runner images

    Pick small, medium or large images that mimic GitHub's runners to different degrees.

  • Dry runs

    -n shows the plan without executing it.

In depth

Getting started

bash
brew install act            # or: winget install nektos.act / scoop / gh extension install nektos/gh-act
act -l                      # list jobs and the events that trigger them
act push                    # run everything a push would run
act pull_request -j test    # one job, as a PR would run it
act -n                      # dry run

The first run asks which default image size to use. "Medium" is a good balance; "micro" is tiny but misses many tools.

Secrets and inputs

bash
act -s GITHUB_TOKEN="$(gh auth token)" --secret-file .secrets
act workflow_dispatch --input environment=staging
act -e event.json           # custom event payload

Matching GitHub more closely

Map runner labels to fuller images when steps need tools that the default images lack:

bash
act -P ubuntu-latest=catthehacker/ubuntu:act-latest

Put common flags in a .actrc file in the repo or your home directory so you don't retype them.

Good to know

  • Steps can detect act through the ACT environment variable, so you can skip deploy steps when running locally (if: ${{ !env.ACT }}).
  • Keep .secrets out of git.

Strengths

  • Cuts the "push, wait five minutes, fix a typo, push again" loop when writing workflows.
  • Lets you debug a failing step interactively on your own machine.
  • Useful for running the same CI checks locally before pushing.

Watch out for

  • It isn't identical to GitHub's hosted runners: images differ, and some actions or tools behave differently.
  • Service containers, caching and some GitHub-specific features have partial support.
  • Only Linux jobs run in Docker; macOS and Windows runners can't be emulated.
  • Full-size runner images are very large (many gigabytes).

Try it in a few minutes

Terminal
brew install act   # or see install docs
act -l          # list jobs
act push        # run the push event

Alternatives

Push and iterate

Accurate but slow; use a scratch branch and workflow_dispatch to iterate.

Dagger

Define pipelines in code so they run identically locally and in any CI.

Earthly / Makefiles

Keep CI logic in scripts that run anywhere, and make the workflow file a thin wrapper.

Related tools

Other tools that share topics with act.

Kiri

runkiri.com
New

A small, fast container runtime for macOS, Windows and Linux that replaces Docker Desktop.

Instead of Docker Desktop

mise

mise.jdx.dev
Gem

One tool to pin Node, Python, Go and more per project, plus env vars and tasks.

Instead of nvm + pyenv + asdf + direnv + ad-hoc scripts

Gotify

gotify.net
Gem

A simple self-hosted server for sending and receiving push notifications.

Instead of Paid push services, Telegram bots or emailing yourself from scripts