Act Complete Guide 2026: Run and Debug GitHub Actions Workflow Locally

What is Act?

Act is an open-source command-line tool that lets you run GitHub Actions Workflow locally, allowing you to test and debug CI/CD pipelines without pushing code to GitHub.

For developers who frequently write GitHub Actions, this is an efficiency booster:

• Fast iteration: Run locally immediately after modifying workflow, no need to wait for GitHub queuing and execution
• Save resources: Don't consume GitHub Actions minutes (especially for private repositories)
• Offline debugging: Test workflows even without network connection
• Security testing: Verify workflow security in an isolated environment, avoiding accidental execution of dangerous operations

Why Do You Need Act?

GitHub Actions is a powerful CI/CD platform, but debugging workflows has one pain point:

Modify .github/workflows/test.yml 
→ git commit 
→ git push 
→ Wait for GitHub queue (could be minutes to hours)
→ Check logs and find errors
→ Repeat the above steps

This cycle is very time-consuming. With Act, you can:

Modify .github/workflows/test.yml 
→ act -j test    # Run locally immediately
→ Check output, fix issues
→ Run again, confirm everything works before pushing

Efficiency improves by at least 10x.

Act vs Other Solutions

Installing Act

macOS (Homebrew)

brew install act

Linux

Ubuntu/Debian:

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

Arch Linux:

yay -S act
# or
paru -S act

Windows

Chocolatey:

choco install act-cli

Scoop:

scoop install act

Verify Installation

act --version
# Output similar to: act version 0.2.x

Quick Start: Running Your First Workflow

Prerequisites

Make sure your project root directory has a .github/workflows/ directory containing at least one workflow file (.yml or .yaml).

List Available Workflows

cd /path/to/your/project
act -l

Example output:

Stage  Job ID  Job name  Workflow name  Workflow file  Events
0      test    Test      CI             ci.yml         push,pull_request
0      build   Build     CI             ci.yml         push,pull_request

Run Specific Job

# Run job named test
act -j test

# Run all jobs
act

# Run workflow triggered by specific event (e.g., pull_request)
act pull_request

Notes on First Run

On first run, Act will download necessary Docker images (usually catthehacker/ubuntu:act-latest), which may take a few minutes. Subsequent runs will use cached images and be faster.

INFO[0000] Using docker host 'unix:///var/run/docker.sock'
INFO[0000] Pulling image 'catthehacker/ubuntu:act-latest'
...

Advanced Usage

1. Using Different Runner Images

Act defaults to Ubuntu images, but you can specify different platforms via the -P parameter:

# Use Ubuntu 22.04
act -P ubuntu-latest=catthehacker/ubuntu:act-22.04

# Use Ubuntu 20.04
act -P ubuntu-latest=catthehacker/ubuntu:act-20.04

# Use lightweight image (faster, but limited functionality)
act -P ubuntu-latest=node:16-buster-slim

2. Passing Secrets and Environment Variables

Many workflows depend on secrets (like API keys, Tokens). You can pass them via .env file or command line:

Method 1: Using .env file

Create a .env file in the project root:

MY_API_KEY=your_secret_key
GITHUB_TOKEN=ghp_xxxxxxxxxxxx

Then run:

act --secret-file .env

Method 2: Pass directly via command line

act -s MY_API_KEY=your_secret_key -s GITHUB_TOKEN=ghp_xxxxxxxxxxxx

3. Parallel Execution of Multiple Jobs

If your workflow has multiple independent jobs, you can speed up with --parallel:

act --parallel

4. Dry Run Mode

Only print steps that will be executed, without actually running:

act -n

5. Custom Working Directory

If the workflow depends on a specific directory structure, you can bind mount:

act --bind

This mounts the current directory into the container, making file modifications take effect in real-time.

Practical Cases

Case 1: Debugging Node.js Project CI

Suppose you have a Node.js project with the following workflow:

# .github/workflows/nodejs.yml
name: Node.js CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

Run locally:

act -j test

If tests fail, Act will display full log output, making it easy to locate issues.

Case 2: Testing Multi-Version Python Matrix

# .github/workflows/python.yml
name: Python Tests

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.9', '3.10', '3.11', '3.12']

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Run tests
        run: pytest

Run tests for all Python versions:

act -j test

Act will automatically iterate through all combinations in the matrix and execute them sequentially.

Case 3: Debugging Docker Builds

# .github/workflows/docker.yml
name: Build Docker Image

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build Docker image
        run: docker build -t myapp:${{ github.sha }} .

      - name: Run tests in container
        run: docker run myapp:${{ github.sha }} npm test

Before running locally, ensure Docker daemon is running:

# Check if Docker is available
docker info

# Run workflow
act -j build

Common Troubleshooting

Issue 1: Permission Errors

Symptom: permission denied while trying to connect to the Docker daemon socket

Solution:

# Add current user to docker group
sudo usermod -aG docker $USER
# Re-login or run newgrp docker

Or run Act with sudo (not recommended):

sudo act

Issue 2: Insufficient Memory

Symptom: OOM (Out of Memory) when running large workflows

Solution: Limit concurrent job count

act --max-parallel 1

Issue 3: Action Not Found

Symptom: unable to find action 'actions/checkout@v4'

Solution: Act needs to download actions from GitHub, ensure network connection is normal. For private actions, you need to set GITHUB_TOKEN.

Issue 4: Environment Variables Not Taking Effect

Symptom: Environment variables referenced in workflow are empty

Solution: Ensure variables are correctly passed via --secret-file or -s, and reference them in workflow using ${{ env.VAR_NAME }} or ${{ secrets.VAR_NAME }}.

Best Practices

1. Always test locally before pushing: Make it a habit to verify workflows with Act after modification
2. Use .env files to manage secrets: Don't hardcode sensitive information, add .env to .gitignore
3. Regularly update Act: brew upgrade act or reinstall to get the latest version
4. Combine with VS Code: Install GitHub Actions extension to preview workflows directly in the editor
5. Keep Act as optional step in CI: Remind contributors to test locally in PR templates

Summary

Act is an essential tool for GitHub Actions developers, shortening what used to be a debugging cycle of minutes or even hours down to seconds. Whether it's a simple unit test workflow or a complex multi-stage deployment pipeline, Act lets you quickly verify locally.

Core Advantages Recap: - ⚡ Fast iteration: Local instant run, no need to wait for GitHub queuing - 💰 Cost savings: Doesn't consume GitHub Actions minutes - 🔒 Security isolation: Runs in containers, doesn't affect host environment - 🛠️ Real environment: Uses same runner images as GitHub, results are reliable

If you frequently write or maintain GitHub Actions workflows, strongly recommend adding Act to your toolkit.

Related Links: - Act GitHub Repository - Act Official Documentation - GitHub Actions Documentation