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](https://github.com/nektos/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: ```bash 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: ```markdown ## 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 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: ```bash 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](resources/troubleshooting.md) — Detailed solutions for common issues