aSkills.dev logo
aSkills.devRegistry
Submit Skill
Verified SOP & TutorialAudited Score 98/100

The Complete Production SOP: How to Deploy and Run act Run GitHub Actions Locally via Docker in Autonomous AI Agents

Step-by-step SOP to install and run act GitHub Actions locally in Codex, Claude Code, and Cursor. Pass mock secrets, reuse containers, and debug CI/CD.

View 1-Click Spec
Target Runtimes:codexclaude-codecursorwindsurf
5 min read • Updated for 2026

Technical Overview & Architectural Context

Autonomous coding agents frequently encounter friction when updating continuous integration workflows. Without local verification tooling, agents push speculative commits to remote repositories (e.g., 'fix CI syntax attempt 4'), exhausting GitHub Actions runner concurrency quotas, polluting git commit histories, and incurring significant cloud compute latency. Moreover, agents struggle to accurately diagnose failures caused by differing runner operating systems, runner filesystem paths, or missing environment variables. Deploying the act-local-github-actions-runner skill equips autonomous agents with deterministic operational standards for nektos/act. By running workflows inside containerized Docker environments mimicking GitHub-hosted runners, the agent locally executes exact job matrix steps, verifies shell scripts, passes synthetic secrets via deterministic mock files, and retains container state with --reuse flags for fast iterative debugging before committing any change to Git.

Prerequisites & Environment Requirements

Codex Desktop, Claude Code CLI, Cursor, or Windsurf installed with terminal execution enabled
Docker Engine or Docker Desktop 24.0+ running with accessible docker.sock
nektos/act installed locally (brew install act, choco install act-cli, or direct binary)
Git 2.40+ initialized with existing .github/workflows directory in workspace root

Verified Search Intents & Long-Tail Queries Solved

SEO Audit Score: 98/100

This operational tutorial is engineered to provide deterministic solutions for these developer search queries:

#install act-local-github-actions-runner in cursor ide#claude code act-local-github-actions-runner rules#codex desktop act-local-github-actions-runner setup tutorial#run github actions locally with act docker agent#test github actions locally without committing act#pass mock secrets act local github actions#debug workflow step act interactive container reuse#how to fix act-local-github-actions-runner agent execution error

Step-by-Step Execution Playbook

1

Local Environment Setup & SKILL.md Mounting

Create the local skill manifest directory and inject verified procedural rules into the agent runtime path.

Autonomous runtimes like Claude Code, Cursor, Windsurf, and Codex Desktop monitor specific configuration directories for deterministic skills. Creating a project-local or global skill directory ensures the agent parses triggers like 'run github actions locally act' and restricts its command execution to documented act parameter topologies.

Terminal Command
mkdir -p .agents/skills/act-local-github-actions-runner && cat <<'EOF' > .agents/skills/act-local-github-actions-runner/SKILL.md --- name: "act-local-github-actions-runner" description: "Test and debug complex GitHub Actions workflows locally without pushing commits to remote Git." metadata: author: "Nektos" version: "1.0.0" runtime_compatibility: - "codex" - "claude-code" - "cursor" - "windsurf" triggers: - "run github actions locally act" - "pass mock secrets act" - "debug workflow step act" permissions: fs_read: true fs_write: "workspace" shell_exec: true net_access: true --- # act Run GitHub Actions Locally via Docker Runs GitHub Actions locally with nektos/act: executing workflows inside Docker containers, simulating events (push, pull_request), passing mock secrets (.secrets), and debugging failing steps interactively. EOF
.agents/skills/act-local-github-actions-runner/SKILL.md
---
name: "act-local-github-actions-runner"
description: "Test and debug complex GitHub Actions workflows locally without pushing commits to remote Git."
metadata:
  author: "Nektos"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "run github actions locally act"
  - "pass mock secrets act"
  - "debug workflow step act"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: true
  net_access: true
---
Production Pro-Tip

Use the micro runner image (`-P ubuntu-latest=node:18-bullseye-slim`) in development to save disk space and drastically speed up container startup times.

Sandbox Gotcha

Ensure your agent executor runtime allows Docker socket access (`/var/run/docker.sock`); otherwise, container spin-up commands will fail with daemon permission errors.

2

Environment Secrets & Dependency Validation

Inject mock secrets and validate Docker socket connectivity without exposing sensitive credentials.

GitHub Actions frequently require repository tokens, cloud keys, or third-party API credentials. The agent must construct a staging `.secrets.local` file containing mock values and ensure `.gitignore` blocks accidental commits of secret fixtures.

Terminal Command
test -S /var/run/docker.sock && echo "Docker socket verified" && grep -qxF '.secrets.local' .gitignore || echo '.secrets.local' >> .gitignore cat <<'EOF' > .secrets.local GITHUB_TOKEN=mock_gh_token_value_for_local_testing NPM_TOKEN=mock_npm_token_000000000000 AWS_ACCESS_KEY_ID=test_dummy_key AWS_SECRET_ACCESS_KEY=test_dummy_secret EOF
Production Pro-Tip

Instruct your agent to supply dummy values rather than reading production secrets unless external network access is explicitly mandated by integration tests.

Sandbox Gotcha

Never add production tokens to `.secrets.local`. Verify that the `.gitignore` pattern matches before instructing the agent to run the workflow.

3

Intent Matching & Trigger Invocation

Execute act targeting specific jobs, workflows, or events using deterministic flags.

Agent runtime intent routers map natural language requests to act terminal invocations. Instructing the agent to specify the exact job with `-j <job_id>` and pass `--secret-file` avoids running unnecessary multi-stage matrices or triggering unneeded deployment stages.

Terminal Command
act push -j test --secret-file .secrets.local -P ubuntu-latest=catthehacker/ubuntu:act-latest --reuse
run-act-test.sh
#!/usr/bin/env bash
set -euo pipefail

JOB_NAME="${1:-test}"
echo "Running workflow job '${JOB_NAME}' locally via act..."
act -j "${JOB_NAME}" \
  --secret-file .secrets.local \
  -P ubuntu-latest=catthehacker/ubuntu:act-latest \
  --reuse \
  --rm=false
Production Pro-Tip

Passing the `--reuse` flag keeps the container alive between runs, allowing subsequent agent steps to skip redownloading npm/pip dependencies.

Sandbox Gotcha

Running `act` without flags executes all workflows listening on `on: [push]`, which can cause high CPU usage or attempt unsupported runner types like macOS.

4

Verification, Linting & Output Quality Gate

Validate GitHub Actions YAML syntax and assert zero non-zero exit codes from local executions.

The agent must perform a two-tier verification: first linting the workflow YAML using actionlint to catch structural and expression syntax bugs, followed by a targeted local dry-run via act to verify runner exit codes.

Terminal Command
actionlint .github/workflows/*.yml && act -l && act push -j test --secret-file .secrets.local
Production Pro-Tip

Running `act -l` lists all detected workflows, event triggers, and jobs without spinning up Docker containers, preserving token budget and computation time.

Sandbox Gotcha

Act does not natively support some proprietary third-party composite actions; ensure actions using proprietary cloud APIs are appropriately mocked in steps.

Real-World Scenario: Locally Debugging a Failing CI Matrix Job with Mock Secrets

Tested Trigger Prompt (Feed directly into Codex, Claude, or Cursor):

“Our 'ci.yml' workflow is failing on pull_request validation for the node-test job. Use act to run github actions locally act, pass mock secrets act with a dummy GITHUB_TOKEN, and debug workflow step act to identify why the test runner fails.”

Deterministic Agent Verification Pipeline:
Audits `.github/workflows/ci.yml` and identifies the `node-test` job structure and required secret inputs.
Generates a temporary `.secrets.local` file containing `GITHUB_TOKEN=mock_token_ci` and checks `.gitignore`.
Executes `act pull_request -j node-test --secret-file .secrets.local -P ubuntu-latest=catthehacker/ubuntu:act-latest` to trigger local execution in Docker.
Detects a failure during container execution caused by a missing Node environment variable in the workflow definition.
Applies the patch to `.github/workflows/ci.yml` and re-runs `act pull_request -j node-test --secret-file .secrets.local --reuse` to verify a successful exit code 0.

Runtime Troubleshooting & Failure Modes

Error: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

Root Cause: The Docker service is either stopped on the host system or the user permissions executing the agent sandbox lack write rights to `/var/run/docker.sock`.

Resolution Command / Fix:
sudo systemctl start docker && sudo chmod 666 /var/run/docker.sock || open -a Docker
Error: Error: Unable to find image 'node:18-bullseye-slim' locally / failed to pull image

Root Cause: act attempted to pull a custom platform image specified in `-P` without valid network connectivity, or the Docker pull rate limit was exceeded.

Resolution Command / Fix:
docker pull catthehacker/ubuntu:act-latest && act -P ubuntu-latest=catthehacker/ubuntu:act-latest

Frequently Asked Questions (act Run GitHub Actions Locally via Docker SOP)

Q:Can I use act Run GitHub Actions Locally via Docker across Codex, Claude Code, and Cursor simultaneously?

Yes. The act-local-github-actions-runner skill conforms to the universal SKILL.md specification. Its prompts, triggers, and execution parameters are universally interpreted across Codex Desktop, Claude Code CLI, Cursor, and Windsurf agent environments.

Q:How does act Run GitHub Actions Locally via Docker prevent context window overflow during long agent sessions?

By isolating execution logs inside terminal streams and prioritizing specific target jobs (`act -j <job>`) instead of full-suite matrix logs, the skill outputs minimal exit-code summaries, preventing the context window from being flooded with multi-megabyte package installation logs.

Q:Does this skill require escalated root or container permissions?

The skill has a security score of 98/100 and only requires standard user permissions capable of communicating with the local Docker daemon socket (`/var/run/docker.sock`). No host root privileges or remote credential exposures are required.

Ready to equip your autonomous agent with act Run GitHub Actions Locally via Docker?

Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.

Get 1-Click Install Spec