Act — Local Workflow Testing

~9 min · act, local, debugging

Level 0Apprentice

0 XP0/101 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

Stop pushing-and-praying

Act (nektos/act) runs your GitHub Actions workflows locally in Docker. Useful for: iterating on workflow YAML without burning CI minutes or polluting the Actions tab with 'fix typo' commits, debugging matrix expansion, and validating expressions.

Install + run

brew install act       # or: gh extension install nektos/gh-act
act -W .github/workflows/ci.yml
act -W .github/workflows/ci.yml -j test    # specific job
act pull_request                               # specific event

Limits

Act runs in Docker; macOS jobs can't run on a Linux Act invocation.
Some GitHub-hosted features (Apple-specific actions, secrets vault, OIDC) don't work locally.
Image differs from GitHub's; expect minor surprises.

Companion tools

actionlint — static lint of workflow YAML. Catches typos in event names, expressions, etc., without running anything.
gh act — GitHub CLI extension that wraps act.

Code

Workflow + actionlint + act loop·bash

# Add a Makefile target that runs both checks
cat <<'EOF' > Makefile
ci-lint:
	actionlint .github/workflows/*.yml

ci-run:
	act -W .github/workflows/ci.yml -j test

ci-all: ci-lint ci-run
EOF

# Iterate without pushing
make ci-all

External links

Exercise

Install act + actionlint. Run them on your repo's workflows. Fix every actionlint warning the same week. Use act the next time you'd otherwise push 'fix workflow' commits.