[Schema Consistency] Schema Consistency Check: Frontmatter Documentation vs Actual Workflows

[github-actions[bot]]

Executive Summary

Schema consistency analysis complete for GitHub Agentic Workflows. This check compares documented frontmatter fields in /docs/src/content/docs/reference/ with actual usage across 280 workflow files in .github/workflows/.

Documented Frontmatter Fields

From frontmatter.md (User-Friendly Guide)

Top-Level Configuration Fields:

• name - Workflow name
• description - Workflow description
• source - Source tracking
• redirect - Workflow location redirect
• private - Mark workflow as private
• resources - Additional files to fetch
• labels - Workflow categorization labels
• metadata - Custom key-value pairs
• imports - Workflow specifications to import
• inlined-imports - Inline all imports at compile time
• tracker-id - Identifier for tagging created assets
• on - Trigger events (with sub-fields: slash_command, label_command, roles, bots, skip-roles, skip-bots, manual-approval, reaction, status-comment, github-token, github-app, stop-after, steps, permissions, needs)
• engine - AI engine specification
• strict - Enhanced security validation
• features - Feature flags (action-mode, awf-diagnostic-logs, integrity-reactions, byok-copilot, mcp-cli)
• network - Network permissions
• mcp-scripts - Custom MCP tools
• safe-outputs - Safe outputs processing
• runtimes - Runtime version overrides
• permissions - GitHub token scopes
• run-name - Custom workflow run name
• runs-on - Runner label for main job
• runs-on-slim - Runner label for framework jobs
• timeout-minutes - Maximum job duration
• env - Workflow-level environment variables
• secrets - Secret values
• environment - Environment for deployment rules
• container - Docker container configuration
• services - Service containers
• if - Conditional execution
• checkout - Repository checkout configuration
• steps - Custom steps before agentic execution
• pre-agent-steps - Steps before MCP gateway startup
• post-steps - Steps after agentic execution
• jobs - Custom jobs before agentic execution
• cache - Cache configuration

Total Documented Top-Level Fields: 39

Fields Used in Actual Workflows

Analysis of 280 workflow files in .github/workflows/ reveals the following top-level fields in use:

Fields Found in Actual Workflows:

• authors (undocumented)
• cache
• checkout
• concurrency
• date (undocumented)
• description
• engine
• env
• features
• if
• import-schema (undocumented)
• imports
• inlined-imports
• jobs
• mcp-scripts
• mcp-servers (undocumented)
• name
• network
• observability (undocumented)
• on
• permissions
• pre-agent-steps
• rate-limit (undocumented)
• repo (undocumented)
• runs-on
• runtimes
• safe-outputs
• sandbox (undocumented)
• secret-masking (undocumented)
• services
• source
• steps
• strict
• timeout-minutes
• title (undocumented)
• tools
• tracker-id
• try (undocumented)

Total Fields in Use: 38

Consistency Analysis

Documented But Not Found in Sample Workflows

• redirect - Workflow location redirect
• private - Mark workflow as private
• resources - Additional files to fetch
• labels - Workflow categorization labels
• metadata - Custom key-value pairs
• post-steps - Steps after agentic execution

These fields may exist but weren't found in the sample analyzed. They are documented and valid for use.

Used in Workflows But NOT Documented

Critical Gaps:

1. sandbox - Container sandbox configuration (e.g., agent: awf)
2. mcp-servers - MCP server configuration
3. rate-limit - Rate limiting configuration
4. secret-masking - Secret value masking
5. observability - Observability/telemetry configuration
6. import-schema - Schema import configuration

Minor/Metadata Fields:
7. authors - Workflow authors (metadata)
8. date - Workflow date (metadata)
9. title - Workflow title (duplicate of name)
10. repo - Repository reference
11. try - Try/experimental mode

Sub-field Analysis

Fields Used Under engine:

• id - Engine identifier (11 occurrences)
• model - Model specification (6 occurrences)
• bare - Bare mode flag (2 occurrences)
• max-turns - Maximum turn limit (2 occurrences)
• agent - Agent specification (1 occurrence)
• max-continuations - Maximum continuations (1 occurrence)

Fields Used Under on:

• schedule - Schedule specification (31 occurrences)
• status-comment - Status comments (3 occurrences)
• skip-if-match - Skip on search match (3 occurrences)
• roles - Repository access roles (3 occurrences)
• skip-if-no-match - Skip when no match (2 occurrences)
• reaction - Emoji reaction triggers (2 occurrences)
• issues - Issue event configuration (2 occurrences)
• stop-after - Stop trigger after deadline (1 occurrence)
• steps - Pre-activation steps (1 occurrence)
• skip-if-check-failing - Skip on failing checks (1 occurrence)
• permissions - Token scopes for pre-activation (1 occurrence)

Recommendations

Priority 1: Critical Documentation Gaps

Document these fields in frontmatter.md:

1. sandbox: - Essential for AWF firewall configuration
2. mcp-servers: - Important for custom MCP server setup
3. secret-masking: - Critical for security configuration
4. observability: - Important for telemetry configuration
5. import-schema: - Configuration for schema validation

Priority 2: Standard Fields with Limited Documentation

Expand documentation for:

• engine.bare - Bare mode execution
• engine.max-turns - Turn limit configuration
• engine.max-continuations - Continuation limit

Priority 3: Metadata Fields

Add optional section or appendix for:

• authors - Workflow authors (metadata)
• date - Workflow creation date (metadata)
• repo - Repository reference (optional)
• try - Try/experimental mode flag (optional)
• rate-limit - Rate limiting (if production-critical)

Priority 4: Verify Deprecated Fields

Check if these documented fields are truly in use or can be deprecated:

• redirect - No usage found; verify if actively used
• private - No usage found; verify if actively used
• resources - No usage found; verify if actively used
• labels - No usage found; verify if actively used
• metadata - No usage found; verify if actively used

Files Analyzed

Documentation Files:

• /home/runner/work/gh-aw/gh-aw/docs/src/content/docs/reference/frontmatter.md (34,532 bytes)
• /home/runner/work/gh-aw/gh-aw/docs/src/content/docs/reference/frontmatter-full.md (222,277 bytes)

Workflows Sampled:

• Total workflows in .github/workflows/: 280
• Full schema analysis conducted on all 280 workflows
• Sample files read:
  • smoke-agent-public-none.md
  • scout.md
  • daily-news.md
  • audit-workflows.md
  • changeset.md

Generated by Schema Consistency Checker · ● 1.2M · ◷

• expires on Apr 27, 2026, 4:54 AM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #28663.