act — Run GitHub Actions Locally

Introduction

act eliminates the slow feedback loop of GitHub Actions development. Instead of pushing commits to test your CI workflows, act runs them locally in Docker containers that mirror the GitHub Actions environment. Change your workflow, run act, see results in seconds — not minutes.

With over 70,000 GitHub stars, act has become essential for any team using GitHub Actions. It saves hours of push-wait-debug cycles and lets you develop CI/CD pipelines with the same rapid iteration you use for code.

What act Does

act reads your .github/workflows/ YAML files, parses the jobs and steps, and executes them in Docker containers that replicate GitHub Actions runners. It supports most Actions features including matrix builds, secrets, services, artifacts, and composite actions.

Architecture Overview

[.github/workflows/*.yml]
        |
   [act CLI]
   Parses workflow YAML
   Resolves action references
        |
   [Docker Engine]
   Creates containers per job
   using GitHub runner images
        |
+-------+-------+
|       |       |
[Job 1]  [Job 2]  [Job N]
Docker   Docker   Docker
container container container
  |        |        |
[Steps: checkout, setup-node, run tests...]
  |        |        |
[Output: logs, artifacts, status]

Self-Hosting & Configuration

# Common act usage patterns

# Run with secrets from .env file
act --secret-file .env

# Run with specific secrets
act -s GITHUB_TOKEN=ghp_xxx -s NPM_TOKEN=npm_xxx

# Use a specific runner image (smaller/faster)
act -P ubuntu-latest=catthehacker/ubuntu:act-latest

# Run with verbose output for debugging
act -v

# Dry run (show what would run)
act -n

# Run matrix builds
act -j build  # runs all matrix combinations

# .actrc — default configuration
# -P ubuntu-latest=catthehacker/ubuntu:act-latest
# -P ubuntu-22.04=catthehacker/ubuntu:act-22.04
# --secret-file .env.act

# Example .github/workflows/ci.yml that works with act
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test
      - run: npm run build

Key Features

• Local Execution — run GitHub Actions without pushing to GitHub
• Fast Feedback — seconds instead of minutes for CI testing
• Docker-Based — containers replicate GitHub runner environments
• Secret Management — load secrets from .env files or CLI flags
• Matrix Support — run matrix strategy builds locally
• Event Simulation — trigger push, pull_request, schedule, and other events
• Selective Runs — run specific jobs or workflows by name
• Offline Development — develop CI pipelines without internet

Comparison with Similar Tools

FAQ

Q: Does act support all GitHub Actions features? A: act supports most features: steps, jobs, matrix, services, secrets, env, artifacts, and composite actions. Some GitHub-specific features (caching, OIDC tokens, GitHub API) have limited or no support.

Q: Which Docker images should I use? A: The default images are large (~12GB). Use catthehacker/ubuntu:act-latest for a smaller (~600MB) image that covers most use cases. Specify in .actrc for persistent configuration.

Q: Can I use act in CI itself? A: Yes, but it is primarily designed for local development. Running act inside CI (Docker-in-Docker) is possible but adds complexity. Use it locally for fast iteration.

Q: How do I handle secrets? A: Create a .env.act file (gitignored) with KEY=VALUE pairs. Run act with --secret-file .env.act. Never commit secrets to your repository.

Sources

• GitHub: https://github.com/nektos/act
• Documentation: https://nektosact.com
• Created by Casey Lee
• License: MIT