Use when testing GitHub Actions workflows locally with act. Covers act CLI usage, Docker configuration, debugging workflows, and troubleshooting common issues when running workflows on your local machine.
Tests GitHub Actions workflows locally using act with Docker, secrets, and environment variables.
/plugin marketplace add thebushidocollective/han/plugin install act@hanThis skill is limited to using the following tools:
Use this skill when testing GitHub Actions workflows locally with act. This covers act CLI commands, Docker setup, debugging, and best practices for fast local iteration on CI/CD workflows.
brew install act
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
choco install act-cli
# or
scoop install act
go install github.com/nektos/act@latest
# Run workflows triggered by push event
act
# Equivalent to
act push
# Pull request event
act pull_request
# Workflow dispatch
act workflow_dispatch
# Custom event
act repository_dispatch -e event.json
# Run specific workflow file
act -W .github/workflows/ci.yml
# Run specific job
act -j build
# Run specific workflow and job
act -W .github/workflows/deploy.yml -j production
# List all workflows and jobs
act -l
# List for specific event
act pull_request -l
# Validate without executing
act --dryrun
# Show what would run
act -n
# Validate specific workflow
act --dryrun -W .github/workflows/ci.yml
# Show workflow graph
act -g
# Show graph for specific event
act pull_request -g
Act uses Docker images to simulate GitHub's runners:
# Use default images (micro - minimal)
act
# Use medium images (more tools)
act -P ubuntu-latest=catthehacker/ubuntu:act-latest
# Use large images (most compatible)
act -P ubuntu-latest=catthehacker/ubuntu:full-latest
Create .actrc file in project root:
-P ubuntu-latest=catthehacker/ubuntu:act-latest
-P ubuntu-22.04=catthehacker/ubuntu:act-22.04
-P ubuntu-20.04=catthehacker/ubuntu:act-20.04
Or use command line:
act -P ubuntu-latest=node:18 \
-P ubuntu-22.04=catthehacker/ubuntu:act-22.04
# Reuse containers between runs (faster)
act --reuse
# Clean up after run
act --rm
Create .secrets in project root:
GITHUB_TOKEN=ghp_your_token_here
NPM_TOKEN=npm_your_token_here
AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret
Add to .gitignore:
.secrets
Run with secrets:
act --secret-file .secrets
# Single secret
act -s GITHUB_TOKEN=ghp_token
# Multiple secrets
act -s GITHUB_TOKEN=ghp_token \
-s NPM_TOKEN=npm_token
# Development secrets
act --secret-file .secrets.dev
# Production secrets
act --secret-file .secrets.prod
# Single variable
act --env NODE_ENV=development
# Multiple variables
act --env NODE_ENV=development \
--env DEBUG=true
Create .env file:
NODE_ENV=development
DEBUG=true
LOG_LEVEL=debug
Run with env file:
act --env-file .env
Act automatically sets these:
GITHUB_ACTOR=nektos/act
GITHUB_REPOSITORY=owner/repo
GITHUB_EVENT_NAME=push
GITHUB_SHA=abc123...
GITHUB_REF=refs/heads/main
ACT=true
# Verbose mode
act -v
# Very verbose (debug)
act -vv
# Interactive mode - pause before each step
act --watch
# Keep container running after workflow
act --reuse
# Then in another terminal
docker ps
docker exec -it <container-id> /bin/bash
# Mount current directory
act --bind
# Mount specific directory
act -b /host/path:/container/path
# Validate workflow syntax
act --dryrun
# Run tests
act -j test
# Run full CI
act
# Edit workflow
vim .github/workflows/ci.yml
# Test immediately
act --reuse -j build
# Iterate quickly
act --reuse -j build
# Run specific matrix combination
act --matrix os:ubuntu-latest --matrix node:20
# Run all combinations
act
# Check Docker is running
docker ps
# Pull required images manually
docker pull catthehacker/ubuntu:act-latest
# Clean up Docker resources
docker system prune -a
# Run with sudo (Linux)
sudo act
# Fix Docker permissions (Linux)
sudo usermod -aG docker $USER
newgrp docker
# Use fuller image
act -P ubuntu-latest=catthehacker/ubuntu:full-latest
# Or install in workflow
- run: |
apt-get update
apt-get install -y some-tool
# Check workflow files exist
ls -la .github/workflows/
# Validate YAML syntax
yamllint .github/workflows/*.yml
# List detected workflows
act -l
Some actions don't work with act:
# Skip action in act
- name: GitHub-only action
if: ${{ !env.ACT }}
uses: github/some-action@v1
# Use alternative in act
- name: Local alternative
if: env.ACT == 'true'
run: echo "Running local version"
✅ Use act --dryrun before running full workflows
✅ Create .actrc for consistent configuration
✅ Use .secrets file and add it to .gitignore
✅ Use --reuse for faster iteration
✅ Test workflows locally before pushing
✅ Use appropriate image sizes for your needs
✅ Document act usage in README
❌ Commit .secrets or .env files
❌ Use latest Docker tags in production
❌ Skip validation with --dryrun
❌ Run act without understanding what it will do
❌ Ignore Docker disk space usage
❌ Assume all actions work perfectly with act
# Platform mappings
-P ubuntu-latest=catthehacker/ubuntu:act-latest
# Default options
--reuse
--secret-file .secrets
--env-file .env
# Container options
--container-architecture linux/amd64
Project-specific overrides in workflows directory.
.git/hooks/pre-push:
#!/bin/bash
echo "Validating workflows..."
act --dryrun
if [ $? -ne 0 ]; then
echo "Workflow validation failed"
exit 1
fi
.PHONY: test-workflows
test-workflows:
act --dryrun
act -j test
.PHONY: ci-local
ci-local:
act --reuse
# Use reuse flag
act --reuse
# Skip checkout if not needed
act --reuse -j test --no-recurse
# Use smaller images for simple tests
act -P ubuntu-latest=node:20-alpine
Act respects GitHub Actions caching:
- uses: actions/cache@v4
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
Cache location on host: ~/.cache/act/
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.