[Schema Consistency] Schema Consistency Analysis Report

[github-actions[bot]]

Summary

This is a comprehensive analysis of schema consistency across the gh-aw project, examining 4 areas: Schema vs Parser implementation, Schema vs Documentation, Schema vs Actual Workflows, and Parser vs Documentation.

---

Schema Fields (top-level)

The main_workflow_schema.json defines 53 top-level frontmatter fields:

Trigger & Activation Fields:

• on (required, complex nested structure)
• command (string, for /command triggers)
• import-schema (object, for validating import inputs)
• imports (array/object, for workflow imports)

Configuration Fields:

• name, description, source, redirect, tracker-id, labels, metadata, private, resources
• engine (default: copilot)
• strict (boolean)
• features (object, feature flags)
• runtimes (runtime version overrides)

Execution Fields:

• run-name, runs-on, runs-on-slim, timeout-minutes, if, concurrency
• environment, container, services
• cache, checkout
• steps, pre-steps, pre-agent-steps, post-steps, jobs

Tools & Permissions:

• tools (tool configuration)
• permissions (GitHub token scopes)
• network (network access control)
• mcp-servers (MCP server definitions)
• mcp-scripts (custom MCP tools)
• sandbox (sandbox configuration)

Output & Advanced:

• safe-outputs (automated output routes)
• cache-memory, repo-memory (memory/persistence)
• secrets, env
• observability (OTLP configuration)
• rate-limit (trigger rate limiting)
• secret-masking (secret masking config)
• check-for-updates (version check toggle)
• inlined-imports (inline imports at compile time)
• run-install-scripts (npm/pip install behavior)
• disable-model-invocation (custom agent flag)
• infer (DEPRECATED: use disable-model-invocation)
• dependencies (DEPRECATED: use imports)

Note: The schema uses required: ["on"], so only the on: field is strictly required.

---

Parser/Workflow Go Struct Fields

The main WorkflowData struct in /pkg/workflow/compiler_types.go (lines 382-494) contains these fields:

Core Fields:

• Name, WorkflowID, Description, Source, Redirect, TrackerID
• FrontmatterName, FrontmatterYAML, FrontmatterHash
• On, Permissions, Network, RunName, Env, EnvSources
• If, TimeoutMinutes

Execution Fields:

• CustomSteps, PreSteps, PreAgentSteps, PostSteps
• RunsOn, RunsOnSlim, Environment, Container, Services
• Jobs (map of custom jobs)
• Tools (map), ParsedTools (structured)

Advanced Fields:

• EngineConfig (extends Engine)
• NetworkPermissions (parsed)
• SandboxConfig (parsed)
• SafeOutputs (parsed)
• MCPScripts (parsed)
• SecretMasking (parsed)
• CacheMemoryConfig, RepoMemoryConfig
• Features (map)
• Runtimes (map)
• Roles, Bots, RateLimit
• CheckoutConfigs, CheckoutDisabled

**Flags & Meta(redacted)

• TrialMode, TrialLogicalRepo
• HasExplicitGitHubTool, InlinedImports
• StrictMode, UpdateCheckDisabled, StaleCheckDisabled
• RunInstallScripts

Documentation matches: All major schema fields have corresponding Go struct fields.

---

Documented Fields

The frontmatter documentation at /docs/src/content/docs/reference/frontmatter.md covers (in order):

1. Trigger Events (on:) — complete section with reactions, status-comment, stop-after, manual-approval, skip-if-match, skip-if-no-match, roles, bots, skip-roles, skip-bots, steps, permissions, github-token, github-app
2. Description (description:)
3. Source Tracking (source:)
4. Private Workflows (private:)
5. Resources (resources:)
6. Labels (labels:)
7. Metadata (`meta(redacted)
8. APM Dependencies (imports: - uses: shared/apm.md)
9. Runtimes (runtimes:)
10. Permissions (permissions:)
11. Repository Access Roles (on.roles:)
12. Bot Filtering (on.bots:)
13. Skip Roles (on.skip-roles)
14. Skip Bots (on.skip-bots)
15. Strict Mode (strict:)
16. Feature Flags (features:)
    • Action Mode (features.action-mode)
    • Copilot BYOK (features.byok-copilot)
    • AWF Diagnostic Logs (features.awf-diagnostic-logs)
    • Reaction-based Trust Signals (features.integrity-reactions)
    • DIFC Proxy (tools.github.integrity-proxy)
17. AI Engine (engine:)
18. Network Permissions (network:)
19. MCP Scripts (mcp-scripts:)
20. Safe Outputs (safe-outputs:)
21. Run Configuration (run-name:, runs-on:, runs-on-slim:, timeout-minutes:)
22. Workflow Concurrency (concurrency:)
23. Environment Variables (env:)
24. Secrets (secrets:)
25. Environment Protection (environment:)
26. Container Configuration (container:)
27. Service Containers (services:)
28. Conditional Execution (if:)
29. Repository Checkout (checkout:)
30. Custom Steps (steps:)
31. Pre-Agent Steps (pre-agent-steps:)
32. Post-Execution Steps (post-steps:)
33. Custom Jobs (jobs:)
34. Cache Configuration (cache:)

---

Inconsistencies Found

Critical (potential bugs)

1. Missing Documentation: disable-model-invocation field

• What schema says: Boolean field for custom agent files to control model invocation (type: boolean)
• What docs say: Not documented in frontmatter.md at all
• Go code: Handled via FrontmatterConfig but no explicit mention in main WorkflowData
• Impact: Users of custom agent files have no guidance on this field
• File references: Schema line ~10, docs gap, pkg/parser/frontmatter_includes_test.go:5 shows usage
• Status: DOCUMENTATION GAP

2. Deprecated infer field handling

• What schema says: Deprecated, use disable-model-invocation instead (type: boolean)
• What docs say: No mention of either field
• Go code: Both fields accepted but disable-model-invocation is preferred
• Impact: Users migrating custom agents may not understand the change
• File references: Schema properties.infer, pkg/parser/include_processor.go: line ~205 handles both
• Status: DOCUMENTATION AND MIGRATION PATH GAP

3. Deprecated dependencies field

• What schema says: APM package references (deprecated, use imports instead)
• What docs say: Mentions it's deprecated, suggests migration to imports: - uses: shared/apm.md
• Go code: Warning is emitted if used (pkg/workflow/compiler_orchestrator_tools.go:172)
• Impact: Good — deprecation is handled and documented
• Status: HANDLED CORRECTLY

4. command field type mismatch

• What schema says: Type is string (single command name)
• What Go code says: Command is []string (multiple command names)
• Documentation says: Described in "Bot Filtering" section mentions command support
• Impact: Schema mismatch but code handles it via parsing/merging
• File references: Schema properties.command, pkg/workflow/compiler_types.go:435 (Command []string)
• Status: TYPE MISMATCH - SCHEMA TOO RESTRICTIVE

5. bots field vs top-level vs on.bots field

• What schema says: Top-level bots field (array of strings) for allowing bot identifiers
• What docs say: Referred to as on.bots: in documentation
• Go code: Handled via data.Bots which is populated from on.bots in frontmatter parsing
• Impact: Schema field location doesn't match code; actual usage is nested under on:
• File references: Schema properties.bots, docs "Bot Filtering", pkg/workflow/compiler_types.go:462
• Status: SCHEMA-CODE LOCATION MISMATCH

6. check-for-updates default behavior

• What schema says: Default is true (boolean, with default: true)
• What docs say: "When true (default), the activation job downloads config.json..."
• What Go code enforces: Flag is checked but default is implemented in compiler
• Impact: Works as documented, but default enforcement location varies
• File references: Schema shows default, pkg/workflow/compiler_activation_job.go:~380
• Status: VERIFIED CORRECT

7. timeout-minutes expression handling

• What schema says: Can be string (for expressions) or number
• What docs say: "Accepts either an integer or a GitHub Actions expression string"
• Go code: Stored as string in WorkflowData
• Impact: Correct, expressions are preserved
• Status: VERIFIED CORRECT

Documentation Gaps

1. observability field

• Status: Field exists in schema but NOT documented in frontmatter.md
• Schema defines: OTLP endpoint configuration for observability
• Go code references: pkg/workflow/compiler_types.go:478 (OTLPEndpoint)
• Impact: Users cannot configure observability without consulting schema directly
• Recommendation: Add observability section to frontmatter.md

2. rate-limit field

• Status: Field exists in schema and is used in code but NOT documented in frontmatter.md
• Schema defines: Rate limiting configuration for workflow triggers
• Go code references: pkg/workflow/compiler_types.go:463 (RateLimit)
• Impact: Rate limiting feature is undiscoverable
• Recommendation: Add rate-limit section to frontmatter.md

3. redirect field

• Status: Field exists in schema, mentioned in code comments, but NOT documented in frontmatter.md
• Schema defines: Workflow location redirect for updates (format: workflow spec or GitHub URL)
• Examples in schema: githubnext/agentics/workflows/ci-doctor-v2.md@main
• Impact: Users cannot use workflow redirect feature without schema knowledge
• Recommendation: Add redirect field documentation to frontmatter.md

4. secret-masking field

• Status: Field exists in schema but NOT documented in frontmatter.md
• Schema defines: Secret masking configuration
• Go code references: pkg/workflow/compiler_types.go:475 (SecretMasking)
• Impact: Feature is hidden from normal documentation path
• Recommendation: Add secret-masking section to frontmatter.md

5. run-install-scripts field

• Status: Field exists in schema but NOT documented in frontmatter.md
• Schema defines: Boolean to control npm/pip install behavior
• Go code references: pkg/workflow/compiler_types.go:493 (RunInstallScripts)
• Default behavior: Documented only in schema description
• Impact: Users don't know they can control install script behavior
• Recommendation: Add run-install-scripts field documentation

6. inlined-imports field

• Status: Field exists in schema but NOT documented in frontmatter.md
• Schema defines: Boolean (default: false) to inline all imports at compile time
• Go code references: pkg/workflow/compiler_types.go:483 (InlinedImports)
• Impact: Advanced import feature is undocumented in user-facing docs
• Recommendation: Add inlined-imports section to imports reference or advanced features

Schema Gaps

1. Schema doesn't define nested on.* field structure

• Issue: Schema has properties.bots as top-level, but actual structure is nested on.bots
• Code implementation: Frontmatter parser extracts from on: section
• Impact: Schema validation at top level doesn't match nested structure
• Recommendation: Schema should use $ref to define on: properties as a separate schema

2. Schema doesn't validate tools.* nested structure

• Issue: tools: field maps to complex nested tools configuration (github, bash, edit, etc.)
• Code handles: Via Tools map[string]any then ParsedTools *Tools with structured parsing
• Schema says: additionalProperties: true for tools (too permissive)
• Impact: Schema can't validate tool names or configurations statically
• Recommendation: Add $defs for tool schemas and use $ref in tools property

3. Missing enum validation for runs-on and runs-on-slim

• Schema: Accepts any string
• Docs say: Only specific runners are supported (ubuntu-latest, ubuntu-24.04, ubuntu-22.04, ubuntu-24.04-arm)
• Impact: Users can specify unsupported runners without schema error
• Recommendation: Add enum constraint to schema

4. Missing enum for engine field

• Schema: Accepts any string, defaults to "copilot"
• Supported values: copilot, claude, codex, crush (from code)
• Impact: Invalid engine names aren't caught by schema
• File references: pkg/constants/engine_constants.go has engine list
• Recommendation: Add enum to schema

5. on.skip-roles and on.skip-bots not in schema on property definition

• Issue: Schema properties.skip-roles and properties.skip-bots exist at top level, but docs show them as on.skip-roles and on.skip-bots
• Code implementation: Correctly nested under on: in parser
• Impact: Schema structure doesn't match actual usage
• Recommendation: Move skip-roles and skip-bots under the on: schema definition

Workflow Violations

No runtime violations found in checked workflow files. The .github/agents/ files are custom agent configs (not triggered workflows), and they correctly use fields like:

• disable-model-invocation: true (field exists in schema)
• description: (field exists in schema)

Example from .github/agents/agentic-workflows.agent.md (lines 1-4):

---
description: GitHub Agentic Workflows...
disable-model-invocation: true
---

---

Summary Table

Category	Count	Status
Schema top-level fields	53	✅ Complete
Documented fields in frontmatter.md	~34	⚠️ Gaps exist
Fields with documentation gaps	6+	❌ Action needed
Critical type mismatches	2	❌ Action needed
Schema location mismatches	2	⚠️ Design issue
Deprecated fields handled	2	✅ Good

---

Recommendations

Priority 1 (Critical)

1. Fix schema-code mismatch for command field - Change schema from string to array, or update code to match single string
2. Document disable-model-invocation and infer fields - Add clear migration guidance from deprecated infer to new disable-model-invocation

Priority 2 (Important)

3. Add documentation for: observability, rate-limit, secret-masking, run-install-scripts, inlined-imports, redirect
4. Fix schema structure for on properties - Nest skip-roles, skip-bots, bots under on in schema definition
5. Add enum validation to schema - Add allowed values for engine, runs-on, runs-on-slim

Priority 3 (Nice to have)

6. Add $defs for tools.* schema - Enable proper validation of tool configurations
7. Create mapping between schema fields and Go struct fields - Helps future maintenance

Warning

⚠️ Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "proxy.golang.org"

See Network Configuration for more information.

Generated by Schema Consistency Checker · ● 613.2K · ◷

• expires on Apr 19, 2026, 4:36 AM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Schema Consistency Checker.

A newer discussion is available at Discussion #27145.