act Quickstart
Use this when AI agents need to run GitHub Actions workflows locally before pushing to GitHub.
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.