[Schema Consistency] Schema Consistency Audit - February 3, 2026

[github-actions[bot]]

This report identifies inconsistencies between the frontmatter schema, parser implementation, documentation, and actual workflow usage.

Summary

• Inconsistencies Found: 4 actionable issues
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Multi-Vector Field Enumeration Analysis
• Analysis Date: February 3, 2026

Critical Findings

1. bots Field Undocumented

Severity: Medium
Category: Schema ↔ Documentation Mismatch

The bots field is fully implemented and used in production workflows but has no documentation.

Evidence:

• ✅ Defined in schema: properties.bots (array of strings)
• ✅ Implemented in parser: pkg/workflow/bots_test.go has comprehensive tests
• ✅ Used in workflows: .github/workflows/test-*.md files use bots: ["agentic-workflows-dev[bot]"]
• ❌ Not documented in docs/src/content/docs/reference/frontmatter.md

Impact: Users cannot discover or use this feature without reading source code or examples.

Recommended Fix: Add a dedicated section in frontmatter.md:

### Bot Filtering (`bots:`)

Configure which GitHub bot accounts can trigger workflows. Useful for allowing specific automation bots while maintaining security controls.

```yaml
bots: ["dependabot[bot]", "renovate[bot]"]
```

When specified, only the listed bot accounts can trigger the workflow. Combine with `roles:` for comprehensive access control.

---

2. tracker-id Field Undocumented

Severity: Medium
Category: Schema ↔ Documentation Mismatch

The tracker-id field is fully implemented and actively used but lacks documentation.

Evidence:

• ✅ Defined in schema with detailed validation rules (8-128 chars, alphanumeric + hyphens/underscores)
• ✅ Schema includes helpful examples: workflow-2024-q1, team-alpha-bot, security_audit_v2
• ✅ Used in multiple workflows: audit-workflows-daily, blog-auditor-weekly, breaking-change-checker
• ❌ Not documented in frontmatter reference

Schema Definition:

{
  "type": "string",
  "minLength": 8,
  "maxLength": 128,
  "pattern": "^[a-zA-Z0-9_-]+$",
  "description": "Optional tracker identifier to tag all created assets..."
}

Impact: Users miss out on this valuable feature for tracking workflow-created assets.

Recommended Fix: Add comprehensive documentation section to frontmatter.md explaining the tracker-id purpose, format constraints, and usage examples.

---

3. secret-masking Field Minimally Documented

Severity: Low
Category: Schema ↔ Documentation Mismatch

The secret-masking field has detailed schema configuration but minimal documentation.

Evidence:

• ✅ Schema defines secret-masking.steps array with GitHub Actions step objects
• ✅ Schema provides examples of custom secret redaction patterns
• ⚠️ Documentation only mentions field name in import/merge contexts
• ❌ No guide on configuring secret-masking.steps

Schema Example:

{
  "name": "Redact custom secrets",
  "run": "find /tmp/gh-aw -type f -exec sed -i 's/password123/REDACTED/g' {} +"
}

Impact: Users may not understand how to implement custom secret masking for their workflows.

Recommended Fix: Add a dedicated section explaining how to configure additional secret redaction steps beyond the built-in masking.

---

4. timeout-minutes vs timeout_minutes Duplication

Severity: Low
Category: Schema Clarity

Both timeout-minutes and timeout_minutes exist as separate top-level properties in the schema.

Evidence:

jq '.properties | keys[]' main_workflow_schema.json | grep timeout
timeout-minutes
timeout_minutes

Analysis: This appears to support both YAML naming conventions (hyphenated and underscored). However, it's unclear if:

• Both are intentionally supported
• One is deprecated
• Parser handles both equivalently

Recommended Action: Document which form is preferred, or confirm both are supported equivalently and note this in documentation.

---

Documentation Gaps

These fields exist in schema but have minimal frontmatter.md coverage:

View Documentation Gap Details

1. runtimes Field

• Status: Documented in imports.md but minimal coverage in main frontmatter reference
• Fix: Add dedicated section with runtime override examples

2. container Field

• Status: Listed as supported GitHub Actions field but not explained
• Fix: Add documentation or reference official GitHub Actions docs

3. services Field

• Status: Listed as supported GitHub Actions field but not explained
• Fix: Add documentation or reference official GitHub Actions docs

4. jobs Field

• Status: Mentioned in safe-outputs context but not fully explained
• Fix: Expand safe-outputs.jobs documentation with examples

---

Schema Validation Observations

These schema patterns were examined and found to be correct by design:

View Validation Notes

cache-memory Under Tools

• Initial concern: cache-memory not as top-level property
• Resolution: Correctly defined under tools.properties.cache-memory ✅
• Status: No issue - this is the intended design

post-steps Flexible Schema

• Pattern: Uses oneOf with flexible object types
• Purpose: Supports full GitHub Actions step syntax
• Status: Intentional design for extensibility ✅

---

Recommendations

Priority 1: Documentation Updates

1. Add bots: field documentation to frontmatter.md
2. Add tracker-id: field documentation to frontmatter.md
3. Expand secret-masking: documentation with configuration examples

Priority 2: Schema Clarity

1. Document or deprecate timeout_minutes vs timeout-minutes duality
2. Add examples for under-documented fields (runtimes, container, services)

Priority 3: Future Audits

1. Validate enum value handling (schema enums vs parser validation)
2. Check required field enforcement consistency
3. Audit nested object structure validation (engine., network., sandbox.*)

---

Strategy Performance

• Strategy: Multi-Vector Field Enumeration Analysis
• Findings: 4 actionable inconsistencies
• Effectiveness: High
• Should Reuse: Yes

Method: Combined field extraction from schema (jq), parser code (grep for YAML tags and frontmatter access), documentation (header analysis), and real workflows (usage validation).

This strategy successfully identified documentation gaps by cross-referencing four independent data sources, ensuring comprehensive coverage.

---

Next Steps

• Add documentation for undocumented fields (bots, tracker-id, secret-masking)
• Clarify timeout field naming convention
• Expand examples for under-documented fields
• Schedule next audit focusing on type validation and enum handling

---

Analysis Workflow: §21619992600

AI generated by Schema Consistency Checker

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