Act Action

Execute GitHub Actions workflows locally using the act tool for fast iteration and debugging.

When to Use This Command

Run this command when you need to:

• Test GitHub Actions workflows on your local machine before pushing to CI
• Debug workflow failures without waiting for remote runners to spin up
• Validate workflow syntax and step logic against your local codebase

Consider alternatives when:

• You need to test workflows that depend on GitHub-hosted secrets not available locally
• Your workflows require specific runner hardware or OS images unavailable via Docker

Quick Start

Configuration

Copy
name: act-action
type: command
category: automation

Example Invocation

Copy
claude command:run act-action --workflow deploy.yml --event push

Example Output

[Detect Workflows] Found 3 workflows in .github/workflows/
[Setup] Docker engine running (v24.0.7)
[Setup] act version 0.2.57 detected
[Run] Executing workflow: deploy.yml (trigger: push)
  Step 1/4: actions/checkout@v4 ... done (0.8s)
  Step 2/4: actions/setup-node@v4 ... done (3.2s)
  Step 3/4: npm ci ... done (12.1s)
  Step 4/4: npm run build ... done (8.4s)
[Result] Workflow completed successfully in 24.5s

Core Concepts

Local Execution Overview

Aspect	Details
Runtime	Docker containers simulating GitHub runner environments
Supported Events	push, pull_request, workflow_dispatch, schedule, and more
Secret Handling	Reads from .env, .secrets, or --secret flags
Platform Support	Linux runners natively; macOS/Windows via custom images

Execution Workflow

.github/workflows/*.yml
        |
   [act --list]
   Discover available workflows
        |
   [act --dry-run]
   Validate syntax and steps
        |
   [act <event>]
   Execute inside Docker
        |
   [Output + Logs]
   Review results locally

Configuration

Parameter	Type	Default	Description
workflow	string	all	Specific workflow file to execute
event	string	push	GitHub event to simulate (push, pull_request, etc.)
secret-file	string	.secrets	Path to file containing secrets as KEY=VALUE
platform	string	ubuntu-latest	Runner platform image to use
verbose	boolean	false	Enable detailed execution logging

Best Practices

1. Use Dry Runs First - Always invoke act --dry-run before full execution to catch YAML syntax errors and missing dependencies without consuming Docker resources.

2. Keep Secrets Separate - Store workflow secrets in a dedicated .secrets file excluded from version control. Never hardcode credentials in workflow files or pass them inline.

3. Pin Docker Images - Specify exact platform images with --platform to ensure consistent behavior across team members and avoid unexpected breakage from image updates.

4. Scope Workflow Runs - Target individual workflows with the -W flag rather than running all discovered workflows. This reduces execution time and isolates failures.

5. Mirror CI Environment - Match your local act configuration (Node version, OS, env vars) as closely as possible to your actual GitHub Actions runners to catch environment-specific issues early.

Common Issues

1. Docker Not Running - Act requires a running Docker daemon. Start Docker Desktop or the Docker service before invoking the command. Verify with docker info.

2. Missing Secrets Cause Step Failures - Workflows referencing ${{ secrets.* }} will fail if secrets are not provided. Create a .secrets file or use --secret KEY=VALUE flags.

3. Platform Image Mismatch - Some GitHub Actions marketplace actions only work on specific runner images. Use --platform ubuntu-latest=catthehacker/ubuntu:act-latest for better compatibility.