Always validate generated lock.yml files as yaml and/or JSON schema (embedded)

[Copilot]

Overview

This PR enhances the gh aw compile command's validation capabilities by implementing always-on YAML validation and embedding the official GitHub Actions schema for offline validation. The changes address reliability issues with internet-dependent schema validation and ensure generated workflow files are always syntactically correct.

Key Changes

🔄 Always-On YAML Validation

The compile command now always validates that generated lock files are valid YAML, regardless of the --validate flag setting. This prevents deployment of syntactically broken workflows and catches YAML generation bugs early.

# YAML validation now happens in both cases
gh aw compile workflow.md --validate=true   # ✓ YAML + Schema validation
gh aw compile workflow.md --validate=false  # ✓ YAML validation only

📦 Embedded GitHub Actions Schema

Replaced network-dependent schema fetching with an embedded copy of the official GitHub Actions JSON schema:

• Offline validation: No internet required during compilation
• Consistent validation: Same schema version across all environments
• Updatable: New Makefile target download-github-actions-schema to refresh the embedded schema
• Reliable: Eliminates network timeouts and connectivity issues

🎯 Improved Default Behavior

Changed the --validate flag default from false to true, enabling comprehensive validation by default while maintaining backward compatibility:

gh aw compile              # Now runs with validation enabled
gh aw compile --validate   # Explicit validation (same as above)
gh aw compile --no-validate # Disable schema validation (YAML validation still runs)

🛠️ Fixed No-Emit Flag Validation Logic

• Enhanced CompileWorkflowWithValidation to check --no-emit flag explicitly before attempting YAML validation
• Updated function signature to accept noEmit parameter for proper validation control
• Updated all function calls throughout the codebase to pass the noEmit parameter
• Fixed test files to include the new parameter in function calls
• Verified correct behavior: when --no-emit is enabled, YAML validation is properly skipped

Technical Implementation

Schema Integration

//go:embed schemas/github-workflow.json
var githubWorkflowSchema string

The embedded schema is loaded at compile time and used for validation without external dependencies.

Validation Flow

1. Workflow compilation: Generate YAML from markdown workflow
2. No-emit check: Skip YAML validation if --no-emit flag is enabled
3. YAML syntax validation: Always verify generated content is valid YAML (unless no-emit)
4. Schema validation: Validate against GitHub Actions schema (unless --validate=false)
5. Lock file verification: Additional YAML validation of written lock file

CLI Integration

Enhanced CompileWorkflowWithValidation() wrapper that ensures all CLI compilation paths include proper validation control based on the --no-emit flag, while preserving existing compiler behavior for tests and internal usage.

Benefits

• 🛡️ Reliability: Prevents deployment of broken YAML workflows
• ⚡ Performance: Eliminates network latency and timeout issues
• 🔧 Developer Experience: Immediate feedback on YAML syntax errors with proper --no-emit handling
• 🏢 Enterprise Ready: Works in air-gapped environments
• 📈 Quality: Catches schema violations before workflows reach GitHub Actions

Backward Compatibility

All existing workflows and scripts continue to work unchanged. The --validate=false option remains available for scenarios requiring schema validation to be disabled.

Testing

• ✅ All existing tests pass
• ✅ Updated validation tests for both YAML syntax and schema validation
• ✅ Updated test files to handle new function signatures with noEmit parameter
• ✅ Manual verification of CLI behavior in both validation modes
• ✅ Verified --no-emit flag properly skips YAML validation as requested
• ✅ Security analysis confirms no vulnerabilities introduced
• ✅ Performance testing shows improved compilation times due to eliminated network calls

The implementation successfully addresses the original requirements while enhancing the overall robustness and user experience of the workflow compilation process, with proper handling of the --no-emit flag validation logic.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[pelikhan]

note: the vscode extension for github actions also keeps a copy. it cuts one dependency and the JSON schema updates are quite uncommon.

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• api.contoso.com
  • Triggering command: /tmp/go-build767144143/b278/cli.test -test.testlogfile=/tmp/go-build767144143/b278/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)