# 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.

## Install

Save as a script file and run:

# act — Run GitHub Actions Locally

## Quick Use
```bash
# Install act
# macOS
brew install act

# Linux
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# Run the default workflow
act

# Run a specific event
act push
act pull_request

# List available workflows
act -l

# Run a specific job
act -j test
```

## 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
```bash
# 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
```

```yaml
# 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
| Feature | act | GitHub Actions (cloud) | Jenkins | GitLab CI local |
|---|---|---|---|---|
| Execution | Local (Docker) | Cloud (GitHub) | Self-hosted | Local via gitlab-runner |
| Speed | Seconds | Minutes | Variable | Seconds |
| Cost | Free | Free tier + paid | Free (self-host) | Free |
| Fidelity | High (most features) | 100% | N/A | High |
| Setup | brew install act | None | Complex | Moderate |
| Best For | Dev/debug workflows | Production CI | Enterprise | GitLab users |

## 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

---
Source: https://tokrepo.com/en/workflows/006a587e-371c-11f1-9bc6-00163e2b0d79
Author: Script Depot