GitHub Actions

Live

The CI/CD pipeline uses GitHub Actions with per-package workflows, path-based triggering, and concurrency controls to keep builds fast and focused.

What It Checks

Workflow Architecture

Each package has a dedicated test workflow, plus cross-cutting workflows for E2E, Storybook, and deployment:

Workflow	Trigger Paths	Key Steps
contracts-tests.yml	packages/contracts/**	Foundry install, bun run test, fork tests
shared-tests.yml	packages/shared/**	bun run coverage, lint
admin-tests.yml	packages/admin/**	Vitest, lint
client-tests.yml	packages/client/**	Vitest, lint
agent-tests.yml	packages/agent/**	Vitest, lint
indexer-tests.yml	packages/indexer/**	Mocha, lint
e2e-tests.yml	Push/PR to main/develop	Playwright with Envio + Docker
storybook.yml	Component file changes	Story coverage check, build
claude-guidance.yml	.claude/**, CLAUDE.md	Guidance consistency check
test-quality.yml	Test file changes	Test quality metrics

How It's Configured

Common Configuration

All workflows share these patterns:

Concurrency Control

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

This ensures only the latest push for a given branch runs, canceling stale builds.

Bun Setup

- name: Setup Bun
  uses: oven-sh/setup-bun@v2
  with:
    bun-version: latest

- name: Install dependencies
  run: bun install --frozen-lockfile

--frozen-lockfile ensures CI uses the exact dependency versions from the lockfile. The bun setup is shared across all workflows.

Permissions

Workflows use minimal permissions (contents: read by default). Write permissions are added only where needed (deployment workflows, PR comment workflows).

Contract Tests

The contracts workflow has two jobs:

1. test -- Unit tests with bun run test using FOUNDRY_PROFILE=test
2. fork -- Fork tests with a 90-minute timeout, requiring RPC URL secrets

Fork tests run against real chain state (Sepolia, Arbitrum, Celo) and use foundry-rs/foundry-toolchain@v1 for Foundry installation.

E2E Tests

The E2E workflow is the most complex, requiring:

1. Bun + Node.js + pnpm (for Envio CLI)
2. Docker (for the Envio indexer database)
3. Envio codegen and setup
4. Playwright browser installation
5. Client build with test environment variables

- name: Build client for E2E
  run: bun run build:client
  env:
    VITE_CHAIN_ID: "11155111"
    VITE_USE_HASH_ROUTER: "true"

The workflow supports manual dispatch with a project selector for targeted E2E runs.

Storybook CI

Triggered by changes to component files in any of the three UI packages:

paths:
  - "packages/shared/src/components/**"
  - "packages/shared/.storybook/**"
  - "packages/admin/src/components/**"
  - "packages/client/src/components/**"

Two gates must pass:

• check:stories -- Verifies all exported components have story files
• build-storybook -- Confirms the static Storybook compiles

Deployment Workflows

Workflow	Purpose
deploy-docs.yml	Deploy Docusaurus docs site
deploy-ipfs.yml	Upload contract metadata to IPFS via Storacha
upload-sourcemaps.yml	Upload source maps for error tracking
lighthouse-ci.yml	Performance audits on deployed sites

Running & Troubleshooting

Adding a New Workflow

When creating a workflow for a new package:

1. Use path-based triggers scoped to the package directory
2. Add concurrency control with cancel-in-progress: true
3. Set permissions: contents: read unless write access is needed
4. Use bun install --frozen-lockfile for reproducible installs
5. Run tests with bun run test (not bun test)

Resources

• Husky Git Hooks -- Local quality gates that run before CI
• Regression Testing -- Regression strategy that CI enforces
• Agentic Evaluation -- Agent-powered code review running in CI
• Test Cases -- Test case strategy behind the CI test suites
• Playwright -- E2E testing framework used in e2e-tests.yml
• Storybook -- Component stories validated by storybook.yml
• Forge -- Foundry testing used in contracts-tests.yml

Next best action

Review the builder glossary for quick definitions of terms used across these guides.

Glossary

• Husky Git Hooks
• Regression Testing