Skip to content

README.md

Latest commit

 

History

History
129 lines (93 loc) · 3.89 KB

README.md

File metadata and controls

129 lines (93 loc) · 3.89 KB

GitHub Actions Workflow Testing

This directory contains GitHub Actions workflows for CI/CD.

Testing Workflows Locally

Quick Local CI Script (Easiest)

The simplest way to run all CI checks locally is using the provided script:

./scripts/ci-local.sh

This script runs the same release-validation surface used by GitHub Actions:

  • Rust fmt, clippy, build, tests, docs
  • WASM build
  • npm package build, test, pack, and smoke install
  • combined Python wheel build, metadata check, and smoke install

No Docker required! This is the fastest way to verify your changes before pushing.

Using act (Full Workflow Simulation)

act is a tool that runs GitHub Actions workflows locally. It can use Docker (default) or run directly on your host machine.

Prerequisites

  • act installed (macOS: brew install act)
  • For Docker mode: Docker must be installed and running
  • For self-hosted mode: No Docker required, but tools (Rust, cargo, etc.) must be installed on your system

Running with Docker (Default)

This provides the most accurate simulation of GitHub Actions' Ubuntu environment:

  1. List all workflows and jobs:

    act -l

  2. Run a specific job:

    act -j build
act -j test
act -j lint
act -j format

  3. Run all jobs for a push event:

    act push

  4. Run with verbose output:

    act -v -j build

  5. Run a specific job with a specific target (for the build matrix):

    # Run build job with wasm32 target
act -j build --matrix target:wasm32-unknown-unknown

Running Without Docker (Self-Hosted)

You can run workflows directly on your host machine without Docker using the -P flag:

For Ubuntu workflows (our CI uses ubuntu-latest):

# Run all jobs without Docker
act push -P ubuntu-latest=-self-hosted

# Run a specific job without Docker
act -j build -P ubuntu-latest=-self-hosted
act -j test -P ubuntu-latest=-self-hosted
act -j lint -P ubuntu-latest=-self-hosted
act -j format -P ubuntu-latest=-self-hosted

For macOS workflows:

act -P macos-latest=-self-hosted

For Windows workflows:

act -P windows-latest=-self-hosted

Note: When running self-hosted, the workflow executes directly on your system. This means:

  • No Docker isolation (uses your system state)
  • Faster execution (no container overhead)
  • May behave differently than GitHub's Ubuntu environment
  • All required tools (Rust, cargo, etc.) must be installed on your host

Tips

  • Docker mode: First run will download Docker images (can take a few minutes)
  • Self-hosted mode: Faster startup, but less isolation
  • Use act -j <job-name> to test individual jobs quickly
  • Use act push to simulate a full push event (runs all jobs)
  • If you get permission errors, act needs to create cache directories in ~/.cache/act
  • For this Rust project, self-hosted mode works well since the workflow only runs Rust commands

Manual Validation

You can validate the YAML syntax without running the workflow:

# Using Ruby (if available)
ruby -ryaml -e "YAML.load_file('.github/workflows/ci.yml'); puts 'YAML syntax is valid'"

# Using Python (if pyyaml is installed)
python3 -c "import yaml; yaml.safe_load(open('.github/workflows/ci.yml'))"

Workflow Structure

The CI workflow includes these jobs:

  1. rust-validation: fmt, clippy, build, tests, docs, and cargo publish dry-runs
  2. wasm-validation: workspace wasm32 build
  3. npm-validation: build/test for @relateby/pattern, @relateby/graph, and @relateby/gram, plus export/type checks for @relateby/pattern and packed-artifact smoke coverage for the public npm surface
  4. python-validation: build/check/smoke for the combined relateby-pattern wheel

The publish workflow validates tagged releases first, then publishes crates.io, npm, and PyPI artifacts in separate jobs.