metabuilder/docs/guides/WORKFLOW_QUICK_REF.md

Workflow Simulation - Quick Reference

Commands

Validation (No dependencies required)

npm run act:validate           # Validate all workflow files

Simulation (No Docker required)

npm run simulate:lint          # Simulate lint job
npm run simulate:build         # Simulate build job
npm run simulate:all           # Simulate all jobs

Diagnostics

npm run act:diagnose           # Check setup and validate workflows

With act (requires act + Docker)

npm run act:lint               # Run lint in Docker
npm run act:build              # Run build in Docker
npm run act:all                # Run full CI in Docker

What Each Tool Does

Tool	Purpose	Requirements	When to Use
act:validate	Check YAML syntax & structure	Python 3	Before commit
simulate:*	Run commands locally	Node.js/Bun	Quick checks
act:diagnose	Check setup & validate	Python 3	Troubleshooting
act:*	Run in Docker container	act + Docker	Full simulation

Workflow Files Fixed

All workflow path references updated from ci.yml to ci/ci.yml:

• ✅ package.json scripts
• ✅ run-act.sh default path
• ✅ diagnose-workflows.sh
• ✅ test-workflows.sh

Security Improvements

• ✅ Pinned all GitHub Actions to specific commit SHAs
• ✅ Fixed unpinned dependency-check/Dependency-Check_Action@main
• ✅ Validation script warns about unpinned actions

New Files

1. validate-workflows.py - Workflow validation without act
2. simulate-workflows.sh - Local job simulation
3. docs/guides/WORKFLOW_SIMULATION.md - Full documentation

Common Use Cases

Before Committing

npm run act:validate

Quick Local Check

npm run simulate:lint

Full Local CI Run

npm run simulate:all

With Docker (if act installed)

npm run act:all

Exit Codes

• 0 - Success
• 1 - Validation/execution failed

Tips

• Use simulate:* for fast iteration
• Use act:* for exact GitHub environment
• Run act:validate in CI/pre-commit hooks
• Check docs/guides/WORKFLOW_SIMULATION.md for details