[Schema Consistency] Schema Consistency Analysis - February 5, 2026

[github-actions[bot]]

Summary

Completed comprehensive schema consistency analysis across 4 key areas: JSON schema definitions, parser/compiler implementation, documentation, and actual workflow usage.

• Critical Issues Found: 1
• Documentation Gaps: 1
• Deprecated Fields Tracked: 1
• Strategy Used: Multi-layer field extraction comparison (new)
• Files Analyzed: 166+ workflows, schema files, 20+ parser/compiler files

---

🚨 Critical Issues

1. Firewall Configuration Fields Not Extracted from YAML

Severity: High
Impact: Configuration fields exist in schema and are used in code, but cannot be set via workflow frontmatter

Details:

• Schema defines (pkg/parser/schemas/main_workflow_schema.json):

  • network.firewall.ssl-bump (boolean)
  • network.firewall.allow-urls (array of strings)
  • network.firewall.cleanup-script (string, deprecated)

• Struct has fields (pkg/workflow/firewall.go:12-22):

  type FirewallConfig struct {
      SSLBump       bool     `yaml:"ssl_bump,omitempty"`
      AllowURLs     []string `yaml:"allow_urls,omitempty"`
      CleanupScript string   `yaml:"cleanup_script,omitempty"`
      // ... other fields that ARE extracted
  }

• Extraction code MISSING (pkg/workflow/frontmatter_extraction_security.go:98-132):

  • The extractFirewallConfig() function only extracts: args, version, log-level
  • It does NOT extract: ssl-bump, allow-urls, cleanup-script
  • These fields remain at their zero values (false, nil, empty string)

• Used downstream (pkg/workflow/firewall.go:195-218):

  • getSSLBumpArgs() function uses SSLBump and AllowURLs to generate AWF command-line arguments
  • These configure HTTPS content inspection for the firewall

Recommendation:
Add extraction logic to extractFirewallConfig() in pkg/workflow/frontmatter_extraction_security.go:

// After line 127, add:

// Extract ssl-bump if present  
if sslBump, hasSslBump := firewallObj["ssl-bump"]; hasSslBump {
    if sslBumpBool, ok := sslBump.(bool); ok {
        config.SSLBump = sslBumpBool
    }
}

// Extract allow-urls if present
if allowUrls, hasAllowUrls := firewallObj["allow-urls"]; hasAllowUrls {
    if urlsSlice, ok := allowUrls.([]any); ok {
        for _, url := range urlsSlice {
            if urlStr, ok := url.(string); ok {
                config.AllowURLs = append(config.AllowURLs, urlStr)
            }
        }
    }
}

// Extract cleanup-script if present (deprecated but still in struct)
if cleanupScript, hasCleanup := firewallObj["cleanup-script"]; hasCleanup {
    if scriptStr, ok := cleanupScript.(string); ok {
        config.CleanupScript = scriptStr
    }
}

---

📖 Documentation Gaps

1. Firewall Advanced Features Not Documented

Issue: The network documentation (docs/src/content/docs/reference/network.md) mentions the log-level field (lines 243-262) but does NOT document:

• ssl-bump: Enable SSL interception for HTTPS URL filtering
• allow-urls: URL patterns to allow when SSL bump is enabled
• cleanup-script: Custom cleanup script path (deprecated)

Current Documentation Coverage:

• ✅ network.firewall (boolean and object form)
• ✅ network.firewall.log-level (enum values documented)
• ✅ network.firewall.version (implied by examples)
• ❌ network.firewall.ssl-bump (NOT documented)
• ❌ network.firewall.allow-urls (NOT documented)
• ❌ network.firewall.cleanup-script (NOT documented, deprecated)

Recommendation:
Even though these fields are currently not extracted (see Critical Issue #1), they should be documented once the extraction bug is fixed. Add to docs/src/content/docs/reference/network.md after the log-level section:

### SSL Bump for HTTPS Inspection

Enable SSL bump to allow the firewall to inspect HTTPS traffic and filter by URL path:

```yaml
network:
  firewall:
    ssl-bump: true
    allow-urls:
      - "https://github.com/githubnext/*"
      - "https://api.github.com/repos/*/issues"
  allowed:
    - defaults
```

**Note**: SSL bump requires the AWF firewall and enables deep packet inspection of HTTPS traffic. Use `allow-urls` to specify URL patterns that should be permitted through the firewall.

---

✅ Schema Improvements (Good News)

1. Engine Configuration: Fully Consistent

Analyzed 166+ workflow files using the engine: field. All observed usage patterns are properly defined in the schema:

• ✓ Simple string engine (e.g., engine: copilot) - ~100+ workflows
• ✓ Extended object with id + properties - ~50+ workflows
• ✓ All subfields (model, max-turns, agent, env, steps, error_patterns, config, args, version, user-agent, command, concurrency) are in schema
• ✓ No undocumented fields found in practice

Validation: Schema at pkg/parser/schemas/main_workflow_schema.json (engine_config definition) is comprehensive and matches real-world usage.

2. Top-Level Fields: All Accounted For

Cross-referenced schema properties with compiler frontmatter access patterns:

Schema fields properly accessed:

• ✓ bots, description, engine, features, github-token, if, mcp-servers, name, network, on, permissions, roles, safe-inputs, safe-outputs, sandbox, secret-masking, source, tools, tracker-id

Schema fields used in WorkflowData struct but accessed differently:

• ✓ cache, imports, runtimes, jobs, steps, labels, metadata - These are extracted through specialized functions in pkg/workflow/frontmatter_extraction_metadata.go and stored in WorkflowData struct fields
• ✓ concurrency, run-name, runs-on, timeout-minutes, env, container, services, post-steps - GitHub Actions passthrough fields rendered directly

Finding: No schema fields are unused. Different access patterns reflect different compilation strategies (direct frontmatter access vs. typed struct extraction).

---

🗑️ Deprecated Fields

1. MCP Server network Field

Status: Properly deprecated
Schema: pkg/parser/schemas/mcp_config_schema.json:150-192

"network": {
  "type": "object",
  "deprecated": true,
  "description": "DEPRECATED: Per-server network configuration is no longer supported. Use top-level workflow 'network:' configuration instead. This field is ignored and will be removed in a future version."
}

Assessment: ✅ Well-documented deprecation with clear migration path. Users are directed to use top-level network: instead.

---

📊 Strategy Performance

Strategy Used: Multi-layer field extraction comparison (ID: strategy-1)

Approach:

1. Extract schema fields using Python JSON parsing
2. Extract parser fields using grep for yaml: tags in Go code
3. Extract compiler fields using frontmatter access pattern detection
4. Cross-compare all three sources for mismatches
5. Deep-dive into nested structures (network.firewall) with line-by-line comparison

Results:

• ✅ Found 1 critical extraction bug (firewall fields)
• ✅ Confirmed 1 documentation gap
• ✅ Validated engine field consistency across 166+ workflows
• ✅ Tracked deprecated field status

Effectiveness: High - This is a new strategy being saved to cache for future runs

---

🎯 Recommendations

Immediate Actions (High Priority)

1. Fix firewall field extraction in pkg/workflow/frontmatter_extraction_security.go

   • Add parsing for ssl-bump, allow-urls, cleanup-script
   • Ensure hyphenated YAML keys map to camelCase struct fields
   • Add tests for these fields in extraction tests

2. Document SSL bump feature in docs/src/content/docs/reference/network.md

   • Add section after log-level documentation
   • Include examples of ssl-bump + allow-urls usage
   • Note that it requires AWF firewall

Future Improvements (Medium Priority)

3. Add integration test for firewall field extraction

   • Test workflow: network.firewall with all fields (version, log-level, ssl-bump, allow-urls)
   • Verify extracted config matches expected FirewallConfig struct
   • Validate generated AWF command includes SSL bump args when configured

4. Schema validation for allow-urls patterns

   • Currently accepts any string array
   • Consider adding pattern validation for URL format ((redacted))
   • Document expected URL pattern syntax

---

📁 Key Files Referenced

Category	File	Line References
Schema	pkg/parser/schemas/main_workflow_schema.json	Network/firewall definition
Schema	pkg/parser/schemas/mcp_config_schema.json	MCP network (deprecated)
Struct	pkg/workflow/firewall.go	Lines 12-22 (FirewallConfig)
Extraction	pkg/workflow/frontmatter_extraction_security.go	Lines 98-132 (incomplete)
Usage	pkg/workflow/firewall.go	Lines 195-218 (getSSLBumpArgs)
Compiler	pkg/workflow/compiler_types.go	WorkflowData struct
Docs	docs/src/content/docs/reference/network.md	Lines 243-262 (log-level)
Docs	docs/src/content/docs/reference/frontmatter.md	Top-level field reference

---

🔄 Next Steps

• Schema definitions analysis
• Parser/compiler implementation check
• Documentation consistency review
• Real workflow usage validation
• Fix firewall field extraction bug
• Add firewall SSL bump documentation
• Add integration tests for firewall config
• Consider URL pattern validation in schema

---

Analysis Methodology: Used day-of-year modulo strategy selection (day 36 → new approach). This run established baseline detection strategies now saved to /tmp/gh-aw/cache-memory/strategies.json for future efficiency improvements.

References:

• §21701616120

AI generated by Schema Consistency Checker

• expires on Feb 12, 2026, 6:47 AM UTC