metabuilder/docs/guides/WORKFLOW_SIMULATION.md

GitHub Actions Workflow Simulation & Validation

This document describes the tools and scripts available for simulating and validating GitHub Actions workflows locally.

Overview

The MetaBuilder project includes comprehensive tooling for:

1. Validating workflow files for syntax and structural issues
2. Simulating workflows locally without Docker (fallback when act is unavailable)
3. Running workflows with act (when available)
4. Diagnosing workflow setup and configuration

Quick Start

Without act (Validation & Simulation)

# Validate all workflow files
npm run act:validate

# Simulate a specific job locally
npm run simulate:lint
npm run simulate:build

# Simulate all jobs in sequence
npm run simulate:all

With act Installed (Full Workflow Testing)

# Run diagnostics
npm run act:diagnose

# Validate workflows
npm run act:validate

# Run specific jobs
npm run act:lint
npm run act:build
npm run act:e2e

# Run all CI jobs
npm run act:all

Available Scripts

Validation Scripts

npm run act:validate

Validates all workflow files without requiring act or Docker.

Checks:

• ✅ YAML syntax validation
• ✅ Required workflow fields (name, on, jobs)
• ✅ Job structure validation
• ✅ Step structure validation
• ⚠️ Security warnings (unpinned actions)
• ⚠️ Best practice recommendations

Example output:

🔍 GitHub Actions Workflow Validation
==================================================

Found 14 workflow file(s)

📄 Validating .github/workflows/ci/ci.yml
   ✅ Structure valid

==================================================
📊 Summary:
   Total files checked: 14
   Total issues: 0
   Total warnings: 0

✅ All workflows are valid!

Simulation Scripts

npm run simulate:lint

Simulates the lint job locally by running the actual commands.

npm run simulate:build

Simulates the build job locally.

npm run simulate:all

Runs all jobs in sequence (prisma-check → typecheck → lint → test-unit → build).

Available jobs:

• prisma-check - Validate Prisma setup
• typecheck - Run TypeScript type check
• lint - Run ESLint
• test-unit - Run unit tests
• build - Build application
• test-e2e - Run E2E tests

Act Scripts (Requires act Installation)

npm run act:diagnose

Checks if act is installed, Docker is running, validates workflow files, and lists available jobs.

npm run act:lint

Runs the lint job using act in a Docker container.

npm run act:build

Runs the build job using act in a Docker container.

npm run act:e2e

Runs the E2E test job using act in a Docker container.

npm run act:all

Runs the entire CI pipeline using act.

Tools & Scripts

1. validate-workflows.py

Python script that validates all GitHub Actions workflow files.

Features:

• YAML syntax validation
• Workflow structure validation
• Security best practice checks
• No external dependencies (uses built-in Python YAML parser)

Usage:

python3 scripts/validate-workflows.py

2. simulate-workflows.sh

Bash script that simulates workflow jobs by running commands locally.

Features:

• Works without Docker or act
• Runs actual commands from workflow definitions
• Supports both npm and bun
• Can run individual jobs or all jobs in sequence

Usage:

bash scripts/simulate-workflows.sh lint
bash scripts/simulate-workflows.sh all

3. diagnose-workflows.sh

Diagnostic script that checks workflow setup.

Checks:

• act installation
• Docker status
• Workflow file existence
• Configuration files (.actrc, .secrets)
• Runs validation automatically

Usage:

bash scripts/diagnose-workflows.sh

4. run-act.sh

Wrapper script for running act with proper configuration.

Features:

• Automatically finds workflow files
• Uses optimized Docker images
• Loads secrets and environment files
• Configurable via command-line arguments

Usage:

bash scripts/run-act.sh -w ci/ci.yml -j lint

5. test-workflows.sh

Interactive testing script for workflows.

Features:

• Dry-run validation
• Interactive job testing
• Syntax validation for multiple jobs

Usage:

bash scripts/test-workflows.sh

Workflow Files

The project has 14 workflow files organized by category:

CI Workflows (ci/)

• ci.yml - Main CI/CD pipeline (lint, typecheck, build, test)
• cli.yml - CLI build workflow
• cpp-build.yml - C++ DBAL daemon build
• detect-stubs.yml - Stub implementation detection

PR Workflows (pr/)

• pr-management.yml - PR labeling and management
• merge-conflict-check.yml - Merge conflict detection
• auto-merge.yml - Automatic PR merging
• code-review.yml - Automated code review

Quality Workflows (quality/)

• quality-metrics.yml - Comprehensive quality metrics
• size-limits.yml - Code size limits
• planning.yml - Planning and design workflow
• deployment.yml - Deployment and monitoring

Other Workflows

• development.yml - Development assistance
• issue-triage.yml - Issue triage and auto-fix

Workflow Path Structure

Important: Workflows are organized in subdirectories:

• ✅ Correct: .github/workflows/ci/ci.yml
• ❌ Incorrect: .github/workflows/ci.yml

All scripts have been updated to use the correct paths.

Common Issues & Solutions

Issue: "act not found"

Solution: Either:

1. Install act: brew install act (macOS) or see act installation guide
2. Use simulation scripts instead: npm run simulate:lint

Issue: "Docker not running"

Solution: Start Docker Desktop or Docker daemon.

Issue: "Workflow file not found"

Solution: Use the correct path with subdirectories:

# Correct
npm run act:lint  # Uses ci/ci.yml

# Or specify full path
bash scripts/run-act.sh -w ci/ci.yml -j lint

Issue: "YAML parsing error"

Solution: Run validation to find the specific issue:

npm run act:validate

Best Practices

Before Committing

npm run act:validate  # Validate workflow syntax
npm run simulate:lint # Quick local check

Before Pushing

npm run act:validate  # Validate workflows
npm run simulate:all  # Run all checks locally
# Or with act:
npm run act:all      # Full CI simulation (requires act)

When Workflow Fails on GitHub

# 1. Validate locally
npm run act:validate

# 2. Simulate the failing job
npm run simulate:lint  # Or other job

# 3. Or use act for exact environment
npm run act:lint

Security Considerations

Pinned Action Versions

All GitHub Actions are pinned to specific commit SHAs for security:

# ✅ Good - Pinned to specific SHA
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2

# ❌ Bad - Unpinned version
- uses: actions/checkout@v4
- uses: actions/checkout@main

The validation script will warn about unpinned actions.

Secrets Management

• Never commit .secrets file
• Use .secrets.example as a template
• Secrets are automatically loaded by act scripts if .secrets exists

Continuous Improvement

The validation script helps maintain workflow quality by:

1. Catching syntax errors before pushing
2. Ensuring consistent structure across workflows
3. Identifying security issues (unpinned actions)
4. Validating best practices

Further Reading

• Act Documentation
• GitHub Actions Documentation
• Workflow Syntax Reference

Summary

Task	Command	Requirements
Validate workflows	npm run act:validate	Python 3
Simulate locally	npm run simulate:lint	Node.js/Bun
Run with act	npm run act:lint	act + Docker
Diagnose setup	npm run act:diagnose	act + Docker
Quick check	npm run simulate:lint	Node.js/Bun
Full pipeline	npm run simulate:all	Node.js/Bun

Choose the appropriate tool based on what you have available:

• Python only: Use act:validate
• Node.js/Bun: Use simulate:* commands
• act + Docker: Use act:* commands for full simulation