act

act - Local GitHub Actions Testing

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "act" with this command: npx skills add vinnie357/claude-skills/vinnie357-claude-skills-act

act - Local GitHub Actions Testing

Activate when testing GitHub Actions workflows locally, debugging workflow issues, or developing actions without committing to remote repositories. This skill covers act installation, configuration, and usage patterns.

When to Use This Skill

Activate when:

  • Testing workflow changes before committing

  • Debugging workflow failures locally

  • Developing new workflows iteratively

  • Validating workflow syntax and logic

  • Testing actions with different events

  • Running workflows without GitHub runners

  • Troubleshooting act-specific issues

Installation

Using mise (Recommended for this project)

The act tool is configured in the github plugin's mise.toml:

Install act via mise

mise install act

Verify installation

act --version

Alternative Installation Methods

macOS (Homebrew):

brew install act

Linux (via script):

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

From source:

git clone https://github.com/nektos/act.git cd act make install

Windows (Chocolatey):

choco install act-cli

How act Works

act reads workflow files from .github/workflows/ and:

  • Determines which actions and jobs to execute

  • Pulls or builds required Docker images

  • Creates containers matching GitHub's runner environment

  • Executes steps in isolated containers

  • Provides output matching GitHub Actions format

Key Concept: act uses Docker to simulate GitHub's runner environment locally.

Prerequisites

  • Docker: act requires Docker to run workflows

  • Workflow files: Valid .github/workflows/*.yml files in repository

Verify Docker is running:

docker ps

Basic Usage

List Available Workflows

List all workflows

act -l

Output:

Stage Job ID Job name Workflow name Workflow file Events

0 build build CI ci.yml push,pull_request

0 test test CI ci.yml push,pull_request

Run Default Event (push)

Run all jobs triggered by push event

act

Run specific job

act -j build

Run specific workflow

act -W .github/workflows/ci.yml

Run Specific Events

Pull request event

act pull_request

Manual workflow dispatch

act workflow_dispatch

Push to specific branch

act push -e .github/workflows/push-event.json

Schedule event

act schedule

Dry Run

Show what would run without executing

act -n

Show with full details

act -n -v

Event Payloads

Custom Event Data

Create event JSON file:

{ "pull_request": { "number": 123, "head": { "ref": "feature-branch" }, "base": { "ref": "main" } } }

Use with act:

act pull_request -e event.json

workflow_dispatch Inputs

{ "inputs": { "environment": "staging", "debug": true } }

act workflow_dispatch -e inputs.json

Secrets Management

Via Command Line

Single secret

act -s GITHUB_TOKEN=ghp_xxxxx

Multiple secrets

act -s API_KEY=key123 -s DB_PASSWORD=pass456

Via .secrets File

Create .secrets file (add to .gitignore):

GITHUB_TOKEN=ghp_xxxxx API_KEY=key123 DB_PASSWORD=pass456

Run with secrets file:

act --secret-file .secrets

Environment Variables

Use existing env var

act -s GITHUB_TOKEN

Set from command

export MY_SECRET=value act -s MY_SECRET

Configuration

.actrc File

Create .actrc in repository root or home directory:

Use specific platform

-P ubuntu-latest=catthehacker/ubuntu:act-latest

Default secrets file

--secret-file .secrets

Default environment

--env-file .env

Container architecture

--container-architecture linux/amd64

Verbose output

-v

Custom Runner Images

Use custom image for platform

act -P ubuntu-latest=my-custom-image:latest

Use medium size images (recommended)

act -P ubuntu-latest=catthehacker/ubuntu:act-latest

Use micro images (faster, less compatible)

act -P ubuntu-latest=node:16-buster-slim

Recommended Images

act supports different image sizes:

Medium images (recommended):

  • Better compatibility with GitHub Actions

  • More pre-installed tools

  • Slower startup but fewer failures

-P ubuntu-latest=catthehacker/ubuntu:act-latest -P ubuntu-22.04=catthehacker/ubuntu:act-22.04

Micro images:

  • Faster startup

  • Minimal pre-installed tools

  • May require additional setup

Environment Variables

Via .env File

Create .env file:

NODE_ENV=test API_URL=http://localhost:3000 LOG_LEVEL=debug

Use with act:

act --env-file .env

Via Command Line

act --env NODE_ENV=test --env API_URL=http://localhost:3000

Advanced Usage

Bind Workspace

Mount local directory into container:

act --bind

Reuse Containers

Keep containers between runs for faster execution:

act --reuse

Specific Platforms

Run on specific platform

act -P ubuntu-latest=ubuntu:latest

Multiple platforms

act -P ubuntu-latest=ubuntu:latest
-P windows-latest=windows:latest

Container Architecture

Specify architecture (useful for M1/M2 Macs)

act --container-architecture linux/amd64

Network Configuration

Use host network

act --container-daemon-socket -

Custom network

act --network my-network

Artifact Server

Enable artifact server on specific port

act --artifact-server-path /tmp/artifacts
--artifact-server-port 34567

Debugging

Verbose Output

Verbose logging

act -v

Very verbose (debug level)

act -vv

Watch Mode

Watch for file changes and re-run

act --watch

Interactive Shell

Drop into shell on failure

act --shell bash

Container Inspection

List act containers

docker ps -a | grep act

Inspect specific container

docker inspect <container-id>

View logs

docker logs <container-id>

Limitations and Differences

Not Supported by act

  • Some GitHub-hosted runner features

  • GitHub Apps and installations

  • OIDC token generation

  • Some GitHub API interactions

  • Certain cache implementations

  • Job summaries and annotations (limited)

Workarounds

Missing tools:

steps:

  • name: Install missing tool run: | if ! command -v tool &> /dev/null; then apt-get update && apt-get install -y tool fi

GitHub API calls:

Use GITHUB_TOKEN from secrets

  • env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: gh api repos/${{ github.repository }}/issues

Common Patterns

Testing Pull Request Workflow

Create PR event payload

cat > pr-event.json << EOF { "pull_request": { "number": 1, "head": { "ref": "feature" }, "base": { "ref": "main" } } } EOF

Run PR workflow

act pull_request -e pr-event.json -j test

CI/CD Pipeline Testing

Test entire CI pipeline

act push

Test specific stages

act push -j build act push -j test act push -j deploy --secret-file .secrets

Matrix Testing

Run matrix strategy locally

act -j test

Test specific matrix combination (modify workflow temporarily)

act -j test --matrix node-version:20

Workflow Development Cycle

1. List jobs

act -l

2. Dry run

act -n -j build

3. Run with verbose output

act -v -j build

4. Iterate and test

act --reuse -j build

Troubleshooting

Docker Issues

Error: Cannot connect to Docker daemon

Start Docker

macOS: Start Docker Desktop

Linux:

sudo systemctl start docker

Error: Permission denied

Add user to docker group (Linux)

sudo usermod -aG docker $USER newgrp docker

Image Pull Issues

Error: Failed to pull image

Use specific image version

act -P ubuntu-latest=ubuntu:22.04

Or use act's recommended images

act -P ubuntu-latest=catthehacker/ubuntu:act-latest

Workflow Not Found

Error: No workflows found

Verify workflow files exist

ls -la .github/workflows/

Check workflow syntax

act -n -v

Secret Issues

Error: Secret not found

List required secrets from workflow

grep -r "secrets." .github/workflows/

Provide via command line

act -s SECRET_NAME=value

Or use secrets file

act --secret-file .secrets

Action Failures

Error: Action not found or fails

Ensure action versions are compatible

Some actions may not work locally

Use alternative actions if needed

Or skip problematic steps locally:

  • name: Problematic step if: github.event_name != 'act' # Skip in act uses: some/action@v1

Platform Differences

Error: Command not found

Use medium-sized images with more tools

act -P ubuntu-latest=catthehacker/ubuntu:act-latest

Or install tools in workflow

  • run: apt-get update && apt-get install -y <tool>

Best Practices

.actrc Configuration

Create .actrc in repository:

-P ubuntu-latest=catthehacker/ubuntu:act-latest --secret-file .secrets --container-architecture linux/amd64 --artifact-server-path /tmp/artifacts

.gitignore Entries

act secrets and config

.secrets .env

act artifacts

/tmp/artifacts/

Conditional Logic for Local Testing

steps:

Skip in local testing

  • name: Deploy if: github.event_name != 'act' run: ./deploy.sh

Run only in local testing

  • name: Local setup if: github.event_name == 'act' run: ./local-setup.sh

Fast Feedback Loop

Use reuse flag for faster iterations

act --reuse -j test

Run specific job being developed

act -j my-new-job -v

Watch mode for continuous testing

act --watch -j test

Integration with Development Workflow

Pre-commit Testing

Test before committing

act -j test && git commit -m "message"

Git hook (.git/hooks/pre-commit)

#!/bin/bash act -j test --quiet

Quick Validation

Validate workflow syntax

act -n

Test specific changes

act -j affected-job

CI Parity

Use same images as CI

act -P ubuntu-latest=ubuntu:22.04

Use same secrets structure

act --secret-file .secrets

Scripts and Automation

Installation Script

The plugin includes an installation script at scripts/install-act.sh :

#!/usr/bin/env bash

Install act via mise or fallback methods

if command -v mise &> /dev/null; then echo "Installing act via mise..." mise install act elif [[ "$OSTYPE" == "darwin"* ]] && command -v brew &> /dev/null; then echo "Installing act via Homebrew..." brew install act elif [[ "$OSTYPE" == "linux-gnu"* ]]; then echo "Installing act via install script..." curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash else echo "Please install act manually: https://github.com/nektos/act" exit 1 fi

act --version

Run with:

chmod +x scripts/install-act.sh ./scripts/install-act.sh

Anti-Fabrication Requirements

  • Execute act --version before documenting version numbers

  • Use act -l to verify actual workflows before claiming their presence

  • Execute docker ps to confirm Docker is running before troubleshooting

  • Run act -n to validate workflow syntax before claiming correctness

  • Execute actual act commands to verify behavior before documenting output format

  • Use docker images to verify available images before recommending specific versions

  • Never claim success rates or performance metrics without actual measurement

  • Execute act -v to observe actual error messages before documenting troubleshooting steps

  • Use Read tool to verify workflow files exist before testing them with act

  • Run actual event payloads through act before claiming they work correctly

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open in GitHubOpen in ClawHub

Related Skills

Related by shared tags or category signals.

Coding

github-workflows

No summary provided by upstream source.

Repository SourceNeeds Review
-6
vinnie357
General

nushell

No summary provided by upstream source.

Repository SourceNeeds Review
-9
vinnie357
General

anti-fabrication

No summary provided by upstream source.

Repository SourceNeeds Review
-8
vinnie357