Use when configuring Docker environments for act, selecting runner images, managing container resources, or troubleshooting Docker-related issues with local GitHub Actions testing.
Limited to specific tools
Additional assets for this skill
This skill is limited to using the following tools:
name: act-docker-setup description: Use when configuring Docker environments for act, selecting runner images, managing container resources, or troubleshooting Docker-related issues with local GitHub Actions testing. allowed-tools:
Use this skill when configuring Docker for act, choosing runner images, managing container resources, and optimizing Docker performance for local GitHub Actions workflow testing.
Act supports three image size categories:
| Size | Image | Tools | Use Case |
|---|---|---|---|
| Micro | node:16-buster-slim | Minimal | Simple Node.js workflows |
| Medium | catthehacker/ubuntu:act-* | Common tools | Most workflows |
| Large | catthehacker/ubuntu:full-* | Everything | Maximum compatibility |
# Latest Ubuntu (22.04)
act -P ubuntu-latest=catthehacker/ubuntu:act-latest
# Specific Ubuntu versions
act -P ubuntu-22.04=catthehacker/ubuntu:act-22.04
act -P ubuntu-20.04=catthehacker/ubuntu:act-20.04
# Full images (larger, more tools)
act -P ubuntu-latest=catthehacker/ubuntu:full-latest
act -P ubuntu-22.04=catthehacker/ubuntu:full-22.04
# Runner images (closest to GitHub)
act -P ubuntu-latest=catthehacker/ubuntu:runner-latest
# Node.js
act -P ubuntu-latest=node:20
act -P ubuntu-latest=node:20-alpine
# Python
act -P ubuntu-latest=python:3.12
act -P ubuntu-latest=python:3.12-slim
# Go
act -P ubuntu-latest=golang:1.22
act -P ubuntu-latest=golang:1.22-alpine
# Ruby
act -P ubuntu-latest=ruby:3.3
act -P ubuntu-latest=ruby:3.3-alpine
Create .actrc in project root for persistent settings:
# Default platform images
-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
# Reuse containers
--reuse
# Container options
--container-architecture linux/amd64
--container-daemon-socket -
# Resource limits
--container-cap-add SYS_PTRACE
--container-cap-add NET_ADMIN
Create .github/workflows/.actrc for workflow-specific settings:
-P ubuntu-latest=node:20
--env-file .env.ci
# Override .actrc settings
act -P ubuntu-latest=python:3.12 --no-reuse
# Reuse containers for faster iteration
act --reuse
# Reuse with specific job
act --reuse -j build
# Force recreate containers
act --rm
# List running act containers
docker ps --filter "label=act"
# Stop all act containers
docker stop $(docker ps -q --filter "label=act")
# Remove all act containers
docker rm $(docker ps -aq --filter "label=act")
# Clean up act volumes
docker volume prune
# Exec into running container
docker exec -it act-<job-name> /bin/bash
# View container logs
docker logs act-<job-name>
# Inspect container config
docker inspect act-<job-name>
Act automatically mounts:
/github/workspace/root/.cache/act# Mount additional directory
act --bind /host/path:/container/path
# Mount multiple directories
act --bind /data:/data --bind /config:/config
# Read-only mount
act --bind /readonly:/readonly:ro
# Configure cache location
export ACT_CACHE_DIR=$HOME/.cache/act
# Clean cache
rm -rf $HOME/.cache/act
# Use default Docker socket
act --container-daemon-socket -
# Use custom socket
act --container-daemon-socket /var/run/docker.sock
# Use Docker Desktop socket (Mac)
act --container-daemon-socket unix:///Users/$USER/.docker/run/docker.sock
# Specify architecture
act --container-architecture linux/amd64
# For Apple Silicon Macs
act --container-architecture linux/arm64
# Use host network
act --network host
# Use custom network
act --network my-network
# Create isolated network
docker network create act-network
act --network act-network
# Set memory limit
act --memory 4g
# Set memory and swap
act --memory 4g --memory-swap 8g
# Limit CPU cores
act --cpus 2
# Set CPU shares
act --cpu-shares 512
# Check Docker disk usage
docker system df
# Clean up unused resources
docker system prune -a
# Remove old act cache
find ~/.cache/act -type d -mtime +30 -exec rm -rf {} +
# Add Linux capabilities
act --container-cap-add SYS_PTRACE
# Drop capabilities
act --container-cap-drop ALL
# Security profile
act --security-opt seccomp=unconfined
# Run in privileged mode (use sparingly)
act --privileged
# Safer: add specific capabilities instead
act --container-cap-add SYS_ADMIN
# Workflow using buildx
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v5
with:
platforms: linux/amd64,linux/arm64
Test with act:
# Enable buildx in act
act --use-gitignore=false \
-P ubuntu-latest=catthehacker/ubuntu:act-latest
# Pull image manually
docker pull catthehacker/ubuntu:act-latest
# Use cached image
act --pull=false
# Force pull latest
act --pull=true
# Fix workspace permissions
act --container-options "--user $(id -u):$(id -g)"
# Run as root (not recommended)
act --container-options "--user root"
# Use custom DNS
act --container-options "--dns 8.8.8.8"
# Use host DNS
act --container-options "--dns-search ."
# Continue on error
act --continue-on-error
# Capture exit code
act; echo $?
Choose the smallest image that meets your needs:
# Fast but limited
act -P ubuntu-latest=node:20-alpine
# Balanced
act -P ubuntu-latest=catthehacker/ubuntu:act-latest
# Comprehensive but slow
act -P ubuntu-latest=catthehacker/ubuntu:full-latest
# Optimize Dockerfile for caching
FROM node:20
# Install system deps first (changes rarely)
RUN apt-get update && apt-get install -y git
# Copy package files (changes sometimes)
COPY package*.json ./
# Install deps (changes sometimes)
RUN npm ci
# Copy source (changes often)
COPY . .
# Run jobs in parallel
act --parallel
# Limit parallelism
act --parallel --jobs 2
Create Dockerfile:
FROM catthehacker/ubuntu:act-latest
# Add custom tools
RUN apt-get update && apt-get install -y \
postgresql-client \
redis-tools \
&& rm -rf /var/lib/apt/lists/*
# Install specific Node version
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
&& apt-get install -y nodejs
# Install global npm packages
RUN npm install -g pnpm yarn
Build and use:
docker build -t my-act-runner .
act -P ubuntu-latest=my-act-runner
# Tag image
docker tag my-act-runner username/act-runner:latest
# Push to Docker Hub
docker push username/act-runner:latest
# Use in team
act -P ubuntu-latest=username/act-runner:latest
✅ Use .actrc for consistent configuration across team
✅ Choose appropriate image size for your needs
✅ Use --reuse during development
✅ Clean up Docker resources regularly
✅ Pin image versions in production workflows
✅ Use layer caching for faster builds
✅ Document image requirements in README
❌ Use :latest tags in production
❌ Run containers in privileged mode unnecessarily
❌ Ignore Docker disk space usage
❌ Use oversized images for simple workflows
❌ Commit large images to version control
❌ Skip Docker resource cleanup
❌ Expose sensitive data in container logs
# Fast iteration setup
cat > .actrc << 'EOF'
-P ubuntu-latest=catthehacker/ubuntu:act-latest
--reuse
--rm=false
--container-architecture linux/amd64
EOF
# Strict validation setup
act --dryrun \
--pull=true \
--no-reuse \
-P ubuntu-latest=catthehacker/ubuntu:full-latest
# Different images per job
act -j backend -P ubuntu-latest=node:20 \
-j frontend -P ubuntu-latest=node:20-alpine \
-j database -P ubuntu-latest=postgres:16