Awesome-omni-skill Run CI/CD 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.

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/devops/run-ci-cd-pipeline-locally" ~/.claude/skills/diegosouzapw-awesome-omni-skill-run-ci-cd-pipeline-locally && rm -rf "$T"

manifest: skills/devops/run-ci-cd-pipeline-locally/SKILL.md

source content

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.

# 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:

# 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)

# 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

# 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

tail

— follow the logs directly.

List Available Jobs

act -l

Run Specific Workflow

act -W .github/workflows/ci.yml

Run Specific Job

act -j <job-name>

Run on Specific Event

act push
act pull_request

Dry Run (Preview Without Executing)

act -n

Pass Secrets

# 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 <job-name>`	Run specific job
`--artifact-server-path <dir>`	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:

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

# 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 <container-id> 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.):

Edit the Dockerfile at

.github/skills/run-ci-pipeline-locally/Dockerfile

Rebuild:

docker build --platform linux/amd64 -t wavecraft-ci:latest .github/skills/run-ci-pipeline-locally/

Test:
```
act -j check-engine ... --pull=false
```