Document and test existing pass-through field validation

[Copilot]

Pass-through frontmatter fields (concurrency, container, environment, env, runs-on, services) already have JSON Schema validation during frontmatter parsing. This catches structural errors at compile time, not runtime.

Changes

• Added comprehensive test suite (pkg/parser/schema_passthrough_validation_test.go)

  • 31 test cases covering all pass-through fields
  • Validates correct acceptance of valid structures (string/object variants)
  • Validates rejection of invalid types, missing required fields, and additional properties

• Enhanced validation documentation

  • Added "Pass-Through Field Validation" section to pkg/workflow/validation.go
  • Updated ValidateMainWorkflowFrontmatterWithSchema function docs with pass-through specifics

Validation Examples

Schema validation already catches these at compile time:

# Invalid container type
concurrency: []
✗ error: at '/concurrency': got array, want string or object

# Missing required field
container:
  env: {TEST: "value"}
✗ error: at '/container': missing property 'image'

# Unknown properties
runs-on:
  labels: ["ubuntu-latest"]
  invalid: "field"
✗ error: additional properties 'invalid' not allowed

No validation logic changes needed - existing JSON Schema in pkg/parser/schemas/main_workflow_schema.json handles all requirements.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Code Quality] Add basic structure validation for pass-through YAML fields (concurrency, container, etc.)</issue_title>
<issue_description>### Description

Several frontmatter fields are extracted as raw YAML sections and passed through to GitHub Actions without validation: concurrency, container, environment, env, runs-on, services. While pass-through behavior is intentional, the lack of basic structure validation can lead to confusing runtime errors in GitHub Actions that could be caught earlier during compilation.

Problem

Current Behavior (in compiler_orchestrator_workflow.go:139-296):

workflowData.Concurrency = c.extractTopLevelYAMLSection(frontmatter, "concurrency")
workflowData.Container = c.extractTopLevelYAMLSection(frontmatter, "container")
workflowData.Environment = c.extractTopLevelYAMLSection(frontmatter, "environment")
// ... etc - no validation of structure

Impact:

• Invalid YAML structures accepted during compilation
• Errors only discovered during GitHub Actions execution
• Confusing error messages from GitHub Actions (not gh-aw)
• Harder to debug configuration issues

Example Scenarios

1. Invalid concurrency:

concurrency: "string"  # Should be object with 'group' field

→ Accepted by compiler, fails in GitHub Actions

2. Malformed container:

container: []  # Should be object, not array

→ Accepted by compiler, fails in GitHub Actions

Suggested Changes

Add basic structure validation for pass-through fields:

Implementation Approach:

1. Define expected structure for each pass-through field (in schema or code)
2. Add validation function: validatePassThroughField(fieldName, value, expectedType)
3. Check field structure matches expectations (object vs string vs array)
4. Provide clear error message if structure is invalid
5. Still pass-through valid structures unchanged

Validation Examples:

• concurrency: Must be object with group field (string)
• container: Must be object or string
• environment: Must be object or string
• runs-on: Must be string or array of strings
• env: Must be object with string values

Files Affected

• pkg/workflow/compiler_orchestrator_workflow.go - Add validation logic
• pkg/workflow/validation_passthrough.go (new) - Validation helpers
• pkg/parser/schemas/main_workflow_schema.json - Optionally enhance schema definitions

Success Criteria

• Basic structure validation for all pass-through fields
• Clear error messages indicating expected structure
• Errors caught during compilation, not at runtime
• Valid structures continue to pass-through unchanged
• Documentation marks fields as "pass-through with validation"
• Unit tests for valid and invalid structures

Alternative Approaches

Option 1 (Recommended): Basic structure validation

• Validates type/shape only (object vs string vs array)
• Still passes through to GitHub Actions for detailed validation
• Catches obvious errors early

Option 2: Full schema validation

• Validates against complete GitHub Actions schema
• More comprehensive but requires maintaining schema
• Potential for false positives if GitHub changes schema

Option 3: Document only

• Mark fields as pass-through in schema comments
• No validation added
• Simplest but provides least user benefit

Source

Extracted from Schema Consistency: Runtime Behavior vs Schema Contracts

Finding: Issue #3 - Pass-Through YAML Sections Without Validation (Medium Priority)

Priority

Medium - Improves user experience and catches errors earlier, but current pass-through behavior is intentional and working.

Estimated Effort

3-5 hours (validation logic + comprehensive testing)

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 13, 2026, 5:22 AM UTC

Comments on the Issue (you are @copilot in this section)

• Fixes [Code Quality] Add basic structure validation for pass-through YAML fields (concurrency, container, etc.) #12679

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.