Local Action Verification

Local Action Verification with act

You are setting up a repository so that Jules (or any agent) can run GitHub Actions workflows locally using act to verify code changes pass CI before pushing.

What You're Setting Up

Two scripts and an agents.md section that enable local CI verification:

1. install-act.sh — Installs act if missing (platform-aware, sudo fallback) 2. run-act.sh — Runs act in the background with log polling to avoid agent timeouts 3. AGENTS.md section — Instructions Jules reads to know how to use these scripts

Setup Steps

Step 1: Copy scripts to the repository

Copy the scripts/ directory from this skill into the target repository at scripts/act/:

Target structure:
scripts/act/
├── install-act.sh
└── run-act.sh

Make sure the scripts are executable:

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

Step 2: Add instructions to AGENTS.md

Append the following section to the repository's AGENTS.md file (create it if it doesn't exist). This is how Jules discovers the local verification capability:

## Local CI Verification

Before pushing code or opening a PR, verify changes pass CI locally using `act`.

### Prerequisites
- Docker must be running
- If `act` is not installed, run: `bash scripts/act/install-act.sh`

### How to Verify

1. Read `.github/workflows/` to find the CI workflow and identify the job ID
2. Run the verification script:

bash scripts/act/run-act.sh "push -j <JOB_ID>"

   With matrix: `bash scripts/act/run-act.sh "push -j <JOB_ID> --matrix <KEY>:<VALUE>"`
3. If the run fails, read the log output, fix the code, and re-run
4. After verification, clean up:

rm -f act_output.log git checkout <any unintended file changes>

### Configuration
- Timeout: `ACT_TIMEOUT=900 bash scripts/act/run-act.sh "..."`  (default: 600s)
- Poll interval: `ACT_POLL=15 bash scripts/act/run-act.sh "..."`  (default: 10s)
- Custom image: pass `-P ubuntu-latest=node:20-bookworm` in the arguments for faster pulls

Step 3: Update .gitignore

Append these entries to .gitignore if they don't already exist:

# act artifacts
act_output.log
.secrets

Step 4: Print next steps for the user

Tell the user: 1. Docker must be installed and running on any machine (or Jules VM) where verification runs 2. act will be auto-installed on first use via scripts/act/install-act.sh 3. If workflows require secrets, create a .secrets file (KEY=VALUE format) — never commit it 4. Commit all generated files

Troubleshooting

• Docker not running: act requires Docker. Ensure the Docker daemon is started.
• Image pull slow: First run downloads ~2GB+. Use -P ubuntu-latest=node:20-bookworm for faster pulls.
• ARM64 issues: On Apple Silicon, add --container-architecture linux/amd64 to act arguments.
• Secrets required: Create a .secrets file and pass --secret-file .secrets in the act arguments.
• Timeout: Increase with ACT_TIMEOUT=1200 bash scripts/act/run-act.sh "...".

Resource References

• Troubleshooting Guide — Detailed solutions for common issues

Local Action Verification

A bootstrapper skill that sets up a repository for local GitHub Actions verification using nektos/act. After setup, Jules can validate CI passes before pushing code.

What It Does

When run, this skill copies scripts and instructions into the target repository:

scripts/act/
├── install-act.sh    # Installs act (platform-aware, sudo fallback)
└── run-act.sh        # Background runner with log polling and timeout

It also adds a Local CI Verification section to the repo's AGENTS.md, which Jules reads to discover and use the scripts during tasks.

How It Works

flowchart TD
    A["🎯 Jules receives task<br/>(e.g. 'refactor X, verify CI')"] --> B["📖 Read AGENTS.md"]

    subgraph prereqs ["Step 1: Prerequisites"]
        B --> C{"Docker running?"}
        C -- No --> C1["⛔ Stop, tell user"]
        C -- Yes --> D{"act installed?"}
        D -- No --> D1["Run scripts/act/install-act.sh"]
        D1 --> E["✅ Ready"]
        D -- Yes --> E
    end

    subgraph analyze ["Step 2: Analyze Workflows"]
        E --> F["Read .github/workflows/"]
        F --> G["Identify job IDs,<br/>matrix configs, secrets"]
    end

    subgraph run ["Step 3: Run in Docker"]
        G --> H["scripts/act/run-act.sh<br/>starts act in background"]
        H --> I["act spins up Docker container"]
        I --> J["GitHub Action runs<br/>(build, test, lint)"]
        J --> K{"Exit code?"}
    end

    subgraph heal ["Self-Heal Loop"]
        K -- "❌ Fail" --> L["Read log output"]
        L --> M["Diagnose & fix code"]
        M --> H
    end

    K -- "✅ Pass" --> N

    subgraph cleanup ["Step 4: Cleanup"]
        N["Remove act_output.log"] --> O["Revert unintended changes"]
        O --> P["Verify git diff"]
    end

    P --> Q["🚀 Ready to push / open PR"]

    style prereqs fill:#1a1a2e,stroke:#16213e,color:#e0e0e0
    style analyze fill:#1a1a2e,stroke:#16213e,color:#e0e0e0
    style run fill:#1a1a2e,stroke:#16213e,color:#e0e0e0
    style heal fill:#2d1b1b,stroke:#8b0000,color:#e0e0e0
    style cleanup fill:#1a1a2e,stroke:#16213e,color:#e0e0e0

After Setup

Once the skill has set up the repository, Jules can verify CI locally whenever it's given a coding task. The skill itself is no longer needed — everything Jules needs is in the repo.

Example Flow

1. Jules receives: "Refactor lib/utils.js and verify CI" 2. Jules reads AGENTS.md → sees "Local CI Verification" instructions 3. Jules runs bash scripts/act/run-act.sh "push -j test" 4. CI passes → Jules pushes / opens PR

Prerequisites

• Docker — Must be installed and running (preinstalled on Jules VMs)
• act — Installed automatically by scripts/act/install-act.sh

Limitations

• act does not support all GitHub Actions features (e.g., service containers, some caching)
• Large Docker images can be slow to pull on first run
• Jobs requiring GitHub-specific secrets need a .secrets file

This is not an officially supported Google product.

Troubleshooting Local Action Verification

Docker Hub Rate Limits

Symptoms: Too Many Requests, pull access denied, or unauthorized errors in the log.

Fix: 1. Set DOCKER_USERNAME and DOCKER_PASSWORD environment variables. 2. Run: echo "$DOCKER_PASSWORD" | docker login --username "$DOCKER_USERNAME" --password-stdin 3. Re-run the action.

Image Pull Failures

Symptoms: Container not found, image download hangs, or architecture mismatch errors.

The default image catthehacker/ubuntu:act-latest is ~20GB. Alternatives:

To override, add -P ubuntu-latest=<image> to the act arguments:

./run-act.sh "push -j test -P ubuntu-latest=node:20-bookworm"

ARM64 (Apple Silicon) Issues

act may pull amd64 images on ARM64 machines, causing slow emulation or crashes.

Fix: Use --container-architecture linux/amd64 explicitly, or pull an ARM64-native image if available.

Secrets and Environment Variables

Jobs that reference ${{ secrets.* }} will fail unless secrets are provided.

Fix: Create a .secrets file (KEY=VALUE format, one per line) and pass it:

./run-act.sh "push -j deploy --secret-file .secrets"

⚠️ Never commit `.secrets`. Add it to .gitignore.

File Permission Issues

act runs as root inside the container. This can cause permission changes to mounted files.

Symptoms: package-lock.json, node_modules, or other files modified after running.

Fix: Revert unintended changes:

git checkout package-lock.json

Timeout / Hanging

Symptoms: run-act.sh runs past the timeout, or the process appears stuck.

Causes:

• A workflow step is waiting for user input
• A network resource is unreachable from inside the container
• The Docker image is still downloading (first run can take 10+ minutes)

Fixes: 1. Increase timeout: ACT_TIMEOUT=1200 ./run-act.sh "..." 2. Check act_output.log for the last step that ran 3. Kill stale containers: docker ps | grep act | awk '{print $1}' | xargs docker kill

Service Containers

act has limited support for services: in workflow files. Jobs using service containers (e.g., Postgres, Redis) may not work.

Workaround: Start the service manually before running act:

docker run -d --name test-postgres -p 5432:5432 -e POSTGRES_PASSWORD=test postgres:15
./run-act.sh "push -j test"
docker stop test-postgres && docker rm test-postgres