thebushidocollective/han/act-local-testing

Name: act-local-testing
Author: thebushidocollective

Claude Code and agent skill by thebushidocollective/han

Trust tier 2

community

By thebushidocollective
Testing
thebushidocollective/han
Plugin tools
plugins/tools/act/skills/act-local-testing/SKILL.md
Updated 15 Apr 2026
Version 1.0.01 version recorded

Source check pending

Checking that the SKILL.md file is still in the repository.

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.

Install

npx vskill@latest install thebushidocollective/han/act-local-testing

SKILL.md

Act - Local Workflow Testing

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.

Installation

macOS

bash

brew install act

Linux

bash

curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Windows

bash

choco install act-cli
# or
scoop install act

From Source

bash

go install github.com/nektos/act@latest

Basic Usage

Run All Workflows

bash

# Run workflows triggered by push event
act
 
# Equivalent to
act push

Run Specific Events

bash

# Pull request event
act pull_request
 
# Workflow dispatch
act workflow_dispatch
 
# Custom event
act repository_dispatch -e event.json

Run Specific Workflows

bash

# 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 Available Workflows

bash

# List all workflows and jobs
act -l
 
# List for specific event
act pull_request -l

Validation and Dry Runs

Dry Run

bash

# Validate without executing
act --dryrun
 
# Show what would run
act -n
 
# Validate specific workflow
act --dryrun -W .github/workflows/ci.yml

Graph Visualization

bash

# Show workflow graph
act -g
 
# Show graph for specific event
act pull_request -g

Docker Configuration

Default Runners

Act uses Docker images to simulate GitHub's runners:

bash

# 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

Custom Platform Images

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:

bash

act -P ubuntu-latest=node:18 \
    -P ubuntu-22.04=catthehacker/ubuntu:act-22.04

Reusing Docker Containers

bash

# Reuse containers between runs (faster)
act --reuse
 
# Clean up after run
act --rm

Secrets Management

Using .secrets File

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:

bash

act --secret-file .secrets

Inline Secrets

bash

# Single secret
act -s GITHUB_TOKEN=ghp_token
 
# Multiple secrets
act -s GITHUB_TOKEN=ghp_token \
    -s NPM_TOKEN=npm_token

Environment-Specific Secrets

bash

# Development secrets
act --secret-file .secrets.dev
 
# Production secrets
act --secret-file .secrets.prod

Environment Variables

Setting Variables

bash

# Single variable
act --env NODE_ENV=development
 
# Multiple variables
act --env NODE_ENV=development \
    --env DEBUG=true

Using .env File

Create .env file:

NODE_ENV=development
DEBUG=true
LOG_LEVEL=debug

Run with env file:

bash

act --env-file .env

GitHub Context Variables

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

Debugging

Verbose Output

bash

# Verbose mode
act -v
 
# Very verbose (debug)
act -vv

Step-by-Step Execution

bash

# Interactive mode - pause before each step
act --watch

Inspect Containers

bash

# Keep container running after workflow
act --reuse
 
# Then in another terminal
docker ps
docker exec -it <container-id> /bin/bash

Bind Mount Local Files

bash

# Mount current directory
act --bind
 
# Mount specific directory
act -b /host/path:/container/path

Common Workflows

Test Before Push

bash

# Validate workflow syntax
act --dryrun
 
# Run tests
act -j test
 
# Run full CI
act

Iterative Development

bash

# Edit workflow
vim .github/workflows/ci.yml
 
# Test immediately
act --reuse -j build
 
# Iterate quickly
act --reuse -j build

Matrix Testing

bash

# Run specific matrix combination
act --matrix os:ubuntu-latest --matrix node:20
 
# Run all combinations
act

Troubleshooting

Docker Issues

bash

# Check Docker is running
docker ps
 
# Pull required images manually
docker pull catthehacker/ubuntu:act-latest
 
# Clean up Docker resources
docker system prune -a

Permission Issues

bash

# Run with sudo (Linux)
sudo act
 
# Fix Docker permissions (Linux)
sudo usermod -aG docker $USER
newgrp docker

Missing Tools

bash

# 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

Workflow Not Found

bash

# Check workflow files exist
ls -la .github/workflows/
 
# Validate YAML syntax
yamllint .github/workflows/*.yml
 
# List detected workflows
act -l

Action Compatibility

Some actions don't work with act:

yaml

# 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"

Best Practices

DO

✅ 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

DON'T

❌ 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

Configuration Files

.actrc

# Platform mappings
-P ubuntu-latest=catthehacker/ubuntu:act-latest
 
# Default options
--reuse
--secret-file .secrets
--env-file .env
 
# Container options
--container-architecture linux/amd64

.github/workflows/.actrc

Project-specific overrides in workflows directory.

CI/CD Integration

Pre-Push Hook

.git/hooks/pre-push:

bash

#!/bin/bash
echo "Validating workflows..."
act --dryrun
if [ $? -ne 0 ]; then
  echo "Workflow validation failed"
  exit 1
fi

Make Target

makefile

.PHONY: test-workflows
test-workflows:
 act --dryrun
 act -j test
 
.PHONY: ci-local
ci-local:
 act --reuse

Performance Tips

Faster Iteration

bash

# 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

Caching

Act respects GitHub Actions caching:

yaml

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

Cache location on host: ~/.cache/act/

Related Skills

act-workflow-syntax: Creating and structuring workflow files
act-docker-setup: Configuring Docker for act
act-advanced-features: Advanced act usage patterns

Security

Security scanPassed, 100 of 100Pattern checks on the skill's files.
Model reviewPassed

See the full security report

Quality evaluation

Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

SKILL.md in the repositoryCheckingplugins/tools/act/skills/act-local-testing/SKILL.md

Popularity

Repository stars: 135
Repository forks: 15
7-day trend score: 25

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 15 Apr 2026, 6 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/thebushidocollective/han/act-local-testing/badge)](https://verified-skill.com/skills/thebushidocollective/han/act-local-testing)

Something wrong with this skill or its page? Tell us.