act Quickstart

Use this when AI agents need to run GitHub Actions workflows locally before pushing to GitHub.

Commands

• act <resource> <action> — Execute act commands
• act workflow list — List all available workflows and jobs from .github/workflows/
• act workflow run — Run a workflow (default: push event)
• act job run — Run a specific job by ID
• act workflow validate — Validate workflow files without running
• act workflow dryrun — Dry run mode - validate workflow and show what would run
• act secret list — List configured secrets from .actrc files
• act secret add — Add a secret for workflow runs
• act workflow watch — Watch for file changes and re-run workflows

1) Install plugin and dependency

supercli plugins learn act
# Install act
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sh
# or: brew install act
act --version
# Install plugin
supercli plugins install ./plugins/act --on-conflict replace --json

2) Validate CLI wiring

act --version
docker --version
supercli plugins doctor act --json

3) Prerequisites

Workflow files must exist in .github/workflows/ directory.

# Verify workflows exist
ls -la .github/workflows/
# Or create one
mkdir -p .github/workflows

4) Core command patterns

List workflows

supercli act workflow list

Run workflows

# Run push event (default)
supercli act workflow run

# Run pull_request event
supercli act workflow run --event pull_request

# Run specific job
supercli act workflow run --job test

# With secrets
supercli act workflow run --secrets '["GITHUB_TOKEN=xxx","API_KEY=yyy"]'

Validate workflows

# Validate without running
supercli act workflow validate

# Dry run mode
supercli act workflow dryrun

Watch mode (auto-reload)

supercli act workflow watch

Job-specific run

supercli act job run --job build

Secrets management

# List configured secrets
supercli act secret list

# Add a secret
supercli act secret add --name GITHUB_TOKEN --value xxx

5) Docker Requirements

act runs workflows in Docker containers:

• Docker must be running
• Default images: catthehacker/ubuntu:act-latest
• Custom images: act -P ubuntu-latest=my-custom-image
• No Docker: act -P ubuntu-latest=-self-hosted

6) Agent workflow: Test before push

# 1. List available workflows
supercli act workflow list

# 2. Dry run to validate
supercli act workflow run --dryrun true

# 3. Run specific job
supercli act workflow run --job test

# 4. Run full workflow
supercli act workflow run

7) Safety levels

Command	Level	Description
workflow list, validate, dryrun, secret list	safe	Read-only or validate
workflow run, job run, secret add	guarded	Runs containers
workflow watch	guarded	Continuous execution

Guard commands may require Docker resources. Use --dryrun true to validate first.