ScriptsApr 13, 2026·3 min read

act — Run GitHub Actions Locally

act lets you run GitHub Actions workflows on your local machine. Test and debug your CI/CD pipelines without pushing to GitHub, using Docker containers to simulate the GitHub Actions runner environment.

Script Depot
Script Depot · Community
TL;DR
Run GitHub Actions workflows on your local machine using Docker containers, no push required.
§01

What it is

act is a command-line tool that runs GitHub Actions workflows on your local machine. It uses Docker containers to simulate the GitHub Actions runner environment, letting you test and debug CI/CD pipelines without pushing commits to GitHub. You point act at your .github/workflows/ directory, and it executes the same steps that would run in GitHub's cloud runners.

This tool targets developers who iterate on CI/CD pipelines and want faster feedback than the push-wait-check cycle. Anyone maintaining complex GitHub Actions workflows with multiple jobs and conditional steps benefits from local testing.

§02

How it saves time or tokens

Every push to test a CI change takes minutes of round-trip time: commit, push, wait for GitHub to schedule the runner, run the workflow, check results. act cuts this loop to seconds by running everything locally. For AI-assisted development where you generate and test workflow files iteratively, this acceleration means faster convergence on working pipelines.

§03

How to use

  1. Install act via Homebrew, Chocolatey, or download the binary
  2. Ensure Docker is running on your machine
  3. Run act in your repository root to execute the default push event workflow
§04

Example

# Install
brew install act

# Run the default push event
act

# Run a specific event
act pull_request

# Run a specific job
act -j build

# List available workflows without running them
act -l

# Pass secrets
act -s GITHUB_TOKEN=your_token

# Use a specific image size (medium is default)
act -P ubuntu-latest=catthehacker/ubuntu:act-latest
§05

Related on TokRepo

§06

Common pitfalls

  • act uses smaller Docker images by default that lack some tools present in GitHub's actual runners; use the full images for better compatibility
  • Service containers (like PostgreSQL in CI) require Docker-in-Docker or host Docker socket mounting to work
  • Some GitHub Actions features like caching and artifact upload have limited or no support in act

Frequently Asked Questions

Does act support all GitHub Actions features?+

act supports most workflow features including jobs, steps, matrix strategies, and environment variables. Some features like caching, artifact upload, and GitHub-hosted runner-specific services have limited support or require workarounds.

Do I need Docker to use act?+

Yes. act uses Docker containers to simulate the GitHub Actions runner environment. Docker Desktop or Docker Engine must be installed and running on your machine.

Can act run workflows with secrets?+

Yes. Pass secrets via command-line flags (-s KEY=value), a .secrets file, or environment variables. act does not access your GitHub repository secrets automatically for security reasons.

How accurate is act compared to real GitHub Actions?+

act is highly accurate for standard workflow steps. Differences arise with GitHub-specific services, custom runner configurations, and some marketplace actions that depend on GitHub's infrastructure. The full Docker images improve accuracy.

Can I use act in my CI pipeline?+

While technically possible, act is designed for local development. Running act inside CI adds complexity without benefit since you are already in a CI environment. Use act for local testing before pushing.

Citations (3)
  • act GitHub— Run GitHub Actions locally using Docker containers
  • act README— Docker-based simulation of GitHub Actions runner environment
  • GitHub Documentation— GitHub Actions workflow syntax reference
Related on TokRepo
DevOps toolsAutomation toolsFeatured workflows

Discussion

Sign in to join the discussion.
No comments yet. Be the first to share your thoughts.

Related Assets

doctest — The Fastest Feature-Rich C++ Testing Framework

doctest is a single-header C++ testing framework designed for minimal compile-time overhead and maximum speed.

Script Depot

Chai — BDD/TDD Assertion Library for Node.js

Chai is a flexible assertion library for Node.js and browsers that supports expect, should, and assert styles.

Script Depot

Supertest — HTTP Assertion Library for Node.js APIs

Supertest provides a high-level API for testing HTTP servers in Node.js with fluent assertion chaining.

Script Depot
◈Home🔍Search👤Me