[Schema Consistency] Schema Consistency Check — 2026-04-29

[github-actions[bot]]

Summary

• Inconsistencies Found: 10 across 3 categories
• Categories Analyzed: Schema ↔ Parser, Schema ↔ Documentation, Parser ↔ Documentation
• Strategy Used: New approach — Import-merging asymmetry detection + Schema enum vs code auto-migration check + Documentation coverage audit
• Analysis Date: 2026-04-29

---

Critical Issues

These are potential bugs or schema/code divergences that could affect workflow behavior.

1. bots import merging silently dropped

File: pkg/workflow/compiler_orchestrator_workflow.go:268

The bots field extracted from imported shared workflows is never applied to the compiled output. MergedBots is populated by the import extractor but never consumed by the compiler:

// compiler_orchestrator_workflow.go:268 — current code (MISSING merge)
workflowData.Bots = c.extractBots(frontmatter)

// compare with SkipBots which IS correctly merged with imports:
workflowData.SkipBots = c.mergeSkipBots(c.extractSkipBots(frontmatter), importsResult.MergedSkipBots)

Meanwhile import_field_extractor.go:262 extracts top-level bots from every imported file into acc.bots → MergedBots. That data is collected but never read by the compiler.

Impact: A shared workflow that defines bots: [dependabot[bot]] at the top level will not have those bots merged when it is imported. The bots list in an importing workflow will be incomplete, which may cause bot-triggered workflows to be incorrectly rejected.

Fix: Apply the same merge pattern used for SkipBots:

workflowData.Bots = c.mergeBots(c.extractBots(frontmatter), importsResult.MergedBots)

---

2. bots field location inconsistency between import extractor and runtime checker

Files: pkg/parser/import_field_extractor.go:262 vs pkg/workflow/role_checks.go:167

• Import extractor reads bots from the top-level of each imported workflow: extractFieldJSONFromMap(fm, "bots", "[]")
• Role checker reads bots from on.bots (nested under the on object): onMap["bots"]
• Schema: Defines bots as a top-level field (not inside the on object schema)

This means a top-level bots: in an imported workflow is extracted by the import machinery but is also the wrong key for the runtime check. The documentation at docs/src/content/docs/reference/frontmatter.md:295 correctly tells users to migrate top-level bots: to on.bots:, but the schema still defines it at the top level, and the import extractor reads the top-level form (not on.bots). All three are slightly out of sync.

---

3. sandbox — deprecated srt/sandbox-runtime values rejected by schema, accepted by code

Files: pkg/parser/schemas/main_workflow_schema.json (sandbox property), pkg/workflow/sandbox.go:114

The schema defines the sandbox string enum as ["default", "awf"]. The schema description mentions: "Note: Legacy 'srt' and 'sandbox-runtime' values are automatically migrated to 'awf'" — but those values are not in the enum, so schema validation (IDEs, JSON schema validators) will report an error for any workflow using sandbox: srt.

// sandbox.go:114 — code accepts and migrates deprecated values:
if sandboxConfig.Type == "srt" || sandboxConfig.Type == "sandbox-runtime" {
    ...
}

Impact: Users with legacy sandbox: srt configurations see IDE/editor schema validation errors, but the workflow still compiles successfully. This can be confusing. The schema should either include these deprecated values in the enum (with a deprecated annotation) or document that the code silently migrates them.

---

Documentation Gaps

These fields are defined in the schema and implemented in code but are not covered in the main reference (docs/src/content/docs/reference/frontmatter.md).

View Documentation Gaps (5 items)

4. tracker-id — in schema and code, missing from frontmatter.md

The tracker-id field has full validation logic in pkg/workflow/frontmatter_extraction_metadata.go:87:

• Minimum 8 characters, alphanumeric + hyphens/underscores only
• Injected as GH_AW_TRACKER_ID env var in both activation and safe-outputs jobs

It appears in frontmatter-full.md:50 and frontmatter-hash-specification.md but has no dedicated section in frontmatter.md.

---

5. run-install-scripts — in schema and code, missing from frontmatter.md

run-install-scripts controls whether npm pre/post install scripts are allowed (supply chain risk feature). It emits a warning in non-strict mode and an error in strict mode.

• Schema: top-level run-install-scripts: boolean
• Code: pkg/workflow/run_install_scripts_validation.go, pkg/workflow/compiler_orchestrator_tools.go:162
• Docs: Zero mentions in frontmatter.md

---

6. secret-masking — in schema and code, missing from frontmatter.md

The secret-masking field allows injecting custom secret redaction steps after the built-in masking steps.

• Schema: { steps: [githubActionsStep] }
• Code: pkg/workflow/compiler_orchestrator_tools.go:57
• Docs: Zero mentions in frontmatter.md

---

7. observability.otlp.headers — string form deprecated in schema but not in docs

The schema marks the string form of headers as deprecated:

"description": "Deprecated: use the map form instead. Comma-separated list of key=value HTTP headers..."

The frontmatter.md documentation at line 853 describes it as "map or string" with no deprecation note, and shows the string form in an example at line 876 without warning.

---

8. infer (deprecated) and disable-model-invocation — in schema, not in frontmatter.md

These are custom-agent fields (Copilot custom agent format) present in the main schema:

• infer: boolean — deprecated alias
• disable-model-invocation: boolean — current replacement

They appear in frontmatter-full.md but are absent from frontmatter.md. If they are intentionally scoped to custom agent files only, a note should explain that in the schema description.

---

Schema Improvements Needed

View Schema Improvement Suggestions

9. Top-level bots field should be marked deprecated in schema

The schema defines bots as a top-level field alongside the on trigger configuration, but the current implementation reads it from on.bots. The documentation at frontmatter.md:295 prompts users to migrate with gh aw fix. The schema should mark top-level bots as deprecated and reference on.bots (or remove it and only define it within the on object schema).

10. engine.concurrency field has no worked examples in documentation

The engine.concurrency field (schema: engine_config.concurrency, code: engine.go:210–235) supports both string and object forms for agent-level GitHub Actions concurrency control. The concurrency.md doc mentions it at a high level (engine.concurrency) but does not show a worked example of the object form with group + cancel-in-progress.

---

Recommendations

1. Fix bots import merging (Critical) — Add MergedBots merge in compiler_orchestrator_workflow.go:268, mirroring the SkipBots pattern. This is a behavioral bug where bots defined in imported shared workflows are silently ignored.

2. Unify bots field location — Decide whether bots lives at top-level or inside on, update schema accordingly (deprecate top-level or update import extractor to use on.bots), and ensure import extractor and role checker read from the same location.

3. Fix sandbox schema to accept deprecated values for validation — Either add srt and sandbox-runtime to the enum with a deprecated annotation, or add a custom validation keyword so IDE validators don't flag workflows using these legacy values that the runtime successfully migrates.

4. Add missing frontmatter.md sections — Add documentation entries for tracker-id, run-install-scripts, secret-masking, and clarify observability.otlp.headers string deprecation.

5. Clarify infer/disable-model-invocation scope — Add a note to the schema and docs clarifying these are custom-agent-format-only fields, not general workflow frontmatter.

---

Strategy Performance

• Strategy Used: New approach (day_mod=9 → exploration mode)
• Key Strategies Developed: Import-merging asymmetry detection, Schema enum vs code auto-migration, Documentation coverage audit
• Findings: 10 items across 3 categories
• Effectiveness: HIGH — found one likely behavioral bug (bots import merging)
• Cached for reuse: Yes — saved to /tmp/gh-aw/cache-memory/strategies.json

---

Next Steps

• Investigate and fix MergedBots not applied in compiler_orchestrator_workflow.go:268
• Audit import field extractor vs role_checks for other field location inconsistencies
• Add srt/sandbox-runtime as deprecated enum values in sandbox schema
• Add tracker-id, run-install-scripts, secret-masking sections to frontmatter.md
• Update observability.otlp.headers docs to note string form is deprecated

References:

• §25091329709

Generated by Schema Consistency Checker · ● 425.7K · ◷

• expires on Apr 30, 2026, 4:53 AM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #29250.