Act

act Skill

Run GitHub Actions workflows locally with act. Use this to test CI pipelines without pushing to GitHub.

Prerequisites

• act installed (brew install act)
• Docker running

Apple Silicon

Always pass --container-architecture linux/amd64 on Apple M-series chips:

act push --container-architecture linux/amd64

Running workflows

Run all jobs triggered by push:

act push

Run a specific job:

act push -j lint

Run multiple specific jobs:

act push -j lint -j test

Run on pull_request event:

act pull_request

Dry run (validate workflow without running containers):

act push -n

Platform limitations

macOS runners

act cannot run macos-latest jobs natively. Skip them or map to a Linux image:

act push -P macos-latest=catthehacker/ubuntu:act-latest

If macOS-specific behavior is needed, test those jobs on real GitHub Actions.

GitHub Actions that need event context

Some GitHub Actions (like gitleaks/gitleaks-action@v2) require the full GitHub event JSON and will fail locally with errors like Cannot read properties of undefined (reading 'owner').

For CI, use the official action:

# .github/workflows/ci.yml — works on GitHub Actions
- uses: gitleaks/gitleaks-action@v2
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
    args: detect --source . --config .gitleaks.toml --no-banner --redact --exit-code=1

For local testing with act, install the CLI manually instead:

# Install gitleaks in the act container
curl -sSfL https://github.com/gitleaks/gitleaks/releases/download/v8.24.2/gitleaks_8.24.2_linux_x64.tar.gz | tar xz
sudo mv gitleaks /usr/local/bin/
gitleaks detect --source . --config .gitleaks.toml --exit-code=1

This applies to any action that depends on github.event context — prefer CLI equivalents when testing locally.

Secrets

Pass secrets via --secret or --secret-file:

act push --secret GITHUB_TOKEN="$(gh auth token)"
act push --secret-file .secrets

The .secrets file format is KEY=VALUE, one per line.

Useful flags

Listing workflows

act -l

Output shows event triggers, job IDs, and job names — useful for finding the right -j target.

Workflow graph

act -g

Shows job dependencies as a graph.

Environment variables and inputs

act push --env NODE_ENV=test --env CI=true
act workflow_dispatch --input version=1.2.3

Common patterns

Test a single job quickly

act push -j lint --container-architecture linux/amd64

Validate workflow syntax without running

act push -n

Run with bind mount (faster iteration)

act push -j test -b --container-architecture linux/amd64

Note: -b mounts the working directory directly into the container instead of copying. Faster, but any file changes inside the container affect your local files.

Debug a failing step

act push -j test -v --container-architecture linux/amd64

The -v flag shows detailed Docker and action output.