# Run Cicd Pipeline Locally > Run the Wavecraft CI checks locally. Prefer the native `cargo xtask` commands for speed; use Docker + `act` only when validating GitHub Actions workflows or Linux-specific behavior. Use when this capability is needed. - Skill: `tomevault-io/run-cicd-pipeline-locally` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/run-cicd-pipeline-locally` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/run-cicd-pipeline-locally/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/run-cicd-pipeline-locally --- # Skill: Run GitHub Actions CI/CD pipeline Locally Use this skill to test CI workflows locally before pushing to GitHub. **Preferred path:** run the native `cargo xtask` commands (fast, no Docker). Use Docker + `act` only when you need to validate workflow YAML or Linux-specific behavior. ## Workflow parity requirement ✅ **Keep an xtask mirror for every workflow file** under `.github/workflows/`. If a workflow changes (or a new one is added), update or add an xtask so local runs stay fast and consistent. Use Docker + `act` only for workflow/YAML-specific checks or Linux-only behavior. | Workflow file | Preferred local mirror | Notes | | ------------------------- | ------------------------------- | --------------------------------------------------------------------------------- | | `ci.yml` | `cargo xtask ci-check` | Full lint + test suite | | `template-validation.yml` | `cargo xtask validate-template` | CLI template generation validation | | `release.yml` | `cargo xtask release` | Build/sign/notarize pipeline | | `cli-release.yml` | `cargo xtask release` | Mirror release steps where applicable; add a dedicated xtask if workflow diverges | | `continuous-deploy.yml` | `cargo xtask release` | Use release pipeline for parity; add a publish-focused xtask if needed | ## Preferred: Native xtask (fast, no Docker) These commands mirror CI checks without container overhead and are the recommended way to validate locally. ```bash # Pre-push validation (lint + tests) cargo xtask ci-check # Template validation (mirrors template-validation.yml) cargo xtask validate-template # Optional targeted runs cargo xtask lint cargo xtask test ``` ## Prerequisites - **Rust toolchain** (stable, with clippy + rustfmt) - **Node.js** + **npm** (for UI checks) ## Docker-based (only when needed) Use Docker + `act` when validating GitHub Actions workflow changes, Linux-specific behavior, or job orchestration. **⚠️ Agent Handoff:** If you don't have terminal execution tools available, delegate to an agent who does (Coder or Tester) to run the Docker/act commands below. ### Prerequisites (Docker path) - **Docker Desktop** must be installed and running - **act** must be installed: `brew install act` - **Wavecraft custom CI image** (recommended): See the “Building the Custom Image” section below ### Quick Start for Wavecraft (Docker) Wavecraft provides a custom Docker image with all dependencies pre-installed: ```bash # Build the custom image (one-time setup) docker build --platform linux/amd64 -t wavecraft-ci:latest .github/skills/run-ci-pipeline-locally/ # Run a specific job act -j check-engine -W .github/workflows/ci.yml \ --container-architecture linux/amd64 \ -P ubuntu-latest=wavecraft-ci:latest \ --pull=false \ --artifact-server-path ./tmp/act-artifacts ``` ### Available CI Jobs | Job | Description | Local Testing | | ---------------- | ---------------------------- | ------------- | | `check-ui` | Prettier, ESLint, TypeScript | ✅ Works | | `test-ui` | Vitest unit tests | ✅ Works | | `prepare-engine` | Build UI + compile Rust | ✅ Works | | `check-engine` | cargo fmt + clippy | ✅ Works | | `test-engine` | cargo test | ✅ Works | ### Run Full Pipeline Locally (Docker) ```bash # Run entire CI workflow act -W .github/workflows/ci.yml \ --container-architecture linux/amd64 \ -P ubuntu-latest=wavecraft-ci:latest \ --pull=false \ --artifact-server-path ./tmp/act-artifacts ``` ## Building the Custom Image The custom image includes: - Ubuntu 22.04 - Node.js 20.x - Rust stable with rustfmt + clippy - GTK, WebKit, X11 development libraries ```bash # Build for linux/amd64 (required for Apple Silicon Macs) docker build --platform linux/amd64 -t wavecraft-ci:latest \ .github/skills/run-ci-pipeline-locally/ # Verify the image docker images | grep wavecraft-ci ``` **Note:** Build takes ~5-10 minutes on first run. ## Commands Reference (Docker) **Important:** Do not combine `act` commands with `head` or `tail` — follow the logs directly. ### List Available Jobs ```bash act -l ``` ### Run Specific Workflow ```bash act -W .github/workflows/ci.yml ``` ### Run Specific Job ```bash act -j ``` ### Run on Specific Event ```bash act push act pull_request ``` ### Dry Run (Preview Without Executing) ```bash act -n ``` ### Pass Secrets ```bash # Use GitHub CLI token act -s GITHUB_TOKEN="$(gh auth token)" # Use secrets file (.secrets with KEY=value format) act --secret-file .secrets ``` ## Key Flags for Wavecraft | Flag | Purpose | | -------------------------------------- | ------------------------------------------- | | `--container-architecture linux/amd64` | Required on Apple Silicon Macs | | `-P ubuntu-latest=wavecraft-ci:latest` | Use custom image with dependencies | | `--pull=false` | Use local image, don't pull from Docker Hub | | `-W .github/workflows/ci.yml` | Specify workflow file | | `-j ` | Run specific job | | `--artifact-server-path ` | Enable local artifact upload/download | ## Limitations (Docker) ### Artifact Upload/Download By default, `actions/upload-artifact` and `actions/download-artifact` fail locally because they require GitHub's artifact server. Use the `--artifact-server-path` flag to enable a local artifact server: ```bash act ... --artifact-server-path /tmp/act-artifacts ``` Artifacts will be stored in the specified directory and can be downloaded by subsequent jobs. ### Caching Differences - `act` doesn't share cache with GitHub Actions - First local run compiles everything from scratch - Subsequent runs with `--reuse` can be faster ### Network Dependencies Some steps require network access: - `cargo` downloads crates - `npm` downloads packages - Git repos are cloned ## Debugging Failed Runs ```bash # Verbose output act -v # Very verbose output act -vv # Keep containers running after failure for inspection act --reuse # Interactive shell in the container docker exec -it bash ``` ## Common Issues | Issue | Solution | | --------------------------------- | --------------------------------------------------- | | Docker not running | Start Docker Desktop | | `--container-architecture` errors | Ensure Docker supports linux/amd64 emulation | | Image pull timeout | Use `--pull=false` with local image | | Permission denied on files | Check Docker volume mounts | | Job uses `macos-latest` | Skip job or test manually | | Missing Linux packages | Rebuild custom image | | Rust compilation slow | Expected on first run; use `--reuse` for subsequent | | `ACTIONS_RUNTIME_TOKEN` error | Add `--artifact-server-path /tmp/act-artifacts` | ## Updating the Custom Image If CI dependencies change (new apt packages, Rust version, etc.): 1. Edit the Dockerfile at `.github/skills/run-ci-pipeline-locally/Dockerfile` 2. Rebuild: `docker build --platform linux/amd64 -t wavecraft-ci:latest .github/skills/run-ci-pipeline-locally/` 3. Test: `act -j check-engine ... --pull=false` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/ronhouben) — claim your Tome and manage your conversions.