act-local-ci
Run GitHub Actions workflows locally with nektos/act to validate CI before pushing.
SKILL.mdpackages/skills/act-local-ci/SKILL.md
GitHubAct Local CI Skill
Quick Reference - Test GitHub Actions workflows locally using nektos/act
Mission
Run GitHub Actions workflows locally before pushing to validate CI/CD pipelines, catch errors early, and reduce iteration time. Uses nektos/act to simulate GitHub Actions runner environment.
Core Capabilities
- Local Workflow Execution: Run
.github/workflows/*.ymlfiles locally - Job Selection: Execute specific jobs or entire workflows
- Event Simulation: Trigger with push, pull_request, workflow_dispatch events
- Secret Injection: Pass secrets securely without committing
- Matrix Testing: Test matrix builds before pushing
- Artifact Handling: Capture and inspect build artifacts
Quick Start
# Run all workflows (default push event)
act
# Run specific workflow
act -W .github/workflows/test.yml
# Run specific job
act -j build
# Simulate pull request event
act pull_request
# Pass secrets
act -s GITHUB_TOKEN=$GITHUB_TOKEN
# List available workflows and jobs
act -l
Prerequisites
# Install act (macOS)
brew install act
# Install act (Linux)
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
# Docker is required
docker --version # Must be installed and running
Common Patterns
Test Before Push
# Validate test workflow passes
act -j test --dryrun # Preview what would run
act -j test # Actually run tests
# If successful, push
git push origin feature-branch
Debug Failing CI
# Run with verbose output
act -v
# Use specific runner image
act -P ubuntu-latest=catthehacker/ubuntu:act-latest
# Keep container for debugging
act --reuse
Matrix Build Testing
# Run all matrix combinations
act -j build
# Run specific matrix combination
act -j build --matrix os:ubuntu-latest
Runner Images
| GitHub Runner | Act Default | Recommended |
|---|---|---|
ubuntu-latest |
node:16-buster-slim |
catthehacker/ubuntu:act-latest |
ubuntu-22.04 |
node:16-buster-slim |
catthehacker/ubuntu:act-22.04 |
ubuntu-20.04 |
node:16-buster-slim |
catthehacker/ubuntu:act-20.04 |
Pass/Fail Criteria
Pass: Workflow executes successfully locally
- All jobs complete with exit code 0
- Artifacts generated as expected
- No timeout or resource errors
Fail: Local execution reveals issues
- Job fails with non-zero exit code
- Missing secrets or environment variables
- Docker resource constraints
- Unsupported GitHub Actions features
Configuration
# .actrc (project root)
-P ubuntu-latest=catthehacker/ubuntu:act-latest
-P ubuntu-22.04=catthehacker/ubuntu:act-22.04
--secret-file .secrets
--env-file .env
# .secrets (gitignored)
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
NPM_TOKEN=npm_xxxxxxxxxxxx
Limitations
- Some GitHub-hosted runner features unavailable locally
${{ secrets.GITHUB_TOKEN }}requires manual token- Service containers need Docker Compose setup
- Large runner images (2-9GB) on first run
Performance Target
Target: <2 minutes for typical test workflow
- Image pull (first run): 2-5 minutes
- Subsequent runs: <30 seconds startup
- Test execution: Depends on project
Need More Detail?
Load: skills/act-local-ci/REFERENCE.md (~20KB)
- Advanced configuration options
- Service container setup
- Troubleshooting common issues
- Integration with ensemble agents