[Schema Consistency] Frontmatter Field Processing Analysis

[github-actions[bot]]

FrontmatterConfig Struct Definition

File: /home/runner/work/gh-aw/gh-aw/pkg/workflow/frontmatter_types.go (Lines 88-158)

All Fields with YAML Tags

Core Workflow Fields:
  - Name              string           `json:"name,omitempty"`
  - Description       string           `json:"description,omitempty"`
  - Engine            string           `json:"engine,omitempty"`
  - Source            string           `json:"source,omitempty"`
  - TrackerID         string           `json:"tracker-id,omitempty"`
  - Version           string           `json:"version,omitempty"`
  - TimeoutMinutes    int              `json:"timeout-minutes,omitempty"`
  - Strict            *bool            `json:"strict,omitempty"`
  - Labels            []string         `json:"labels,omitempty"`

Configuration Sections:
  - Tools             *ToolsConfig     `json:"tools,omitempty"`
  - MCPServers        map[string]any   `json:"mcp-servers,omitempty"`
  - RuntimesTyped     *RuntimesConfig  `json:"-"`
  - Runtimes          map[string]any   `json:"runtimes,omitempty"`
  - Jobs              map[string]any   `json:"jobs,omitempty"`
  - SafeOutputs       *SafeOutputsConfig `json:"safe-outputs,omitempty"`
  - SafeInputs        *SafeInputsConfig  `json:"safe-inputs,omitempty"`
  - PermissionsTyped  *PermissionsConfig `json:"-"`

Event & Trigger Configuration:
  - On                map[string]any   `json:"on,omitempty"`
  - Permissions       map[string]any   `json:"permissions,omitempty"`
  - Concurrency       map[string]any   `json:"concurrency,omitempty"`
  - If                string           `json:"if,omitempty"`

Network & Sandbox Configuration:
  - Network           *NetworkPermissions `json:"network,omitempty"`
  - Sandbox           *SandboxConfig      `json:"sandbox,omitempty"`

Plugin Configuration:
  - Plugins           any              `json:"plugins,omitempty"`
  - PluginsTyped      *PluginsConfig   `json:"-"`
  - PluginsRepos      []string         `json:"-"`
  - PluginsToken      string           `json:"-"`

Feature Flags & Settings:
  - Features          map[string]any   `json:"features,omitempty"`
  - Env               map[string]string `json:"env,omitempty"`
  - Secrets           map[string]any   `json:"secrets,omitempty"`

Workflow Execution Settings:
  - RunsOn            string           `json:"runs-on,omitempty"`
  - RunName           string           `json:"run-name,omitempty"`
  - Steps             []any            `json:"steps,omitempty"`
  - PostSteps         []any            `json:"post-steps,omitempty"`
  - Environment       map[string]any   `json:"environment,omitempty"`
  - Container         map[string]any   `json:"container,omitempty"`
  - Services          map[string]any   `json:"services,omitempty"`
  - Cache             map[string]any   `json:"cache,omitempty"`

Import & Inclusion:
  - Imports           any              `json:"imports,omitempty"`
  - Include           any              `json:"include,omitempty"`

Metadata:
  - Metadata          map[string]string `json:"metadata,omitempty"`
  - SecretMasking     *SecretMaskingConfig `json:"secret-masking,omitempty"`
  - GithubToken       string           `json:"github-token,omitempty"`

Command/Bot Configuration:
  - Roles             []string         `json:"roles,omitempty"`
  - Bots              []string         `json:"bots,omitempty"`
  - RateLimit         *RateLimitConfig `json:"rate-limit,omitempty"`

Top 20 Most Frequently Accessed Frontmatter Fields in pkg/workflow

Based on comprehensive grep analysis of non-test files:

Rank	Field Name	Access Count	Primary Usage Files	Access Patterns
1	on	18+ occurrences	filters.go, stop_after.go, role_checks.go, frontmatter_extraction_yaml.go, compiler_safe_outputs.go, compiler_filters_validation.go, schedule_preprocessing.go, manual_approval.go	Event trigger configuration extraction, manipulation, condition evaluation
2	safe-outputs	4 occurrences	safe_outputs_config.go, safe_jobs.go	Safe output configuration validation
3	permissions	3 occurrences	frontmatter_extraction_yaml.go, strict_mode_validation.go	Permissions parsing and strict mode validation
4	network	1 occurrence	frontmatter_extraction_security.go	Network permissions extraction
5	sandbox	1 occurrence	frontmatter_extraction_security.go	Sandbox configuration extraction
6	engine	1 occurrence	engine.go	Engine type determination
7	roles	1 occurrence	role_checks.go	Role-based access control extraction
8	bots	1 occurrence	role_checks.go	Bot identifier extraction
9	rate-limit	1 occurrence	role_checks.go	Rate limit configuration extraction
10	safe-inputs	2 occurrences	safe_inputs_parser.go	Safe input validation
11	features	1 occurrence	frontmatter_extraction_metadata.go	Feature flags extraction
12	description	1 occurrence	frontmatter_extraction_metadata.go	Metadata extraction
13	source	1 occurrence	frontmatter_extraction_metadata.go	Source URL extraction
14	tracker-id	1 occurrence	frontmatter_extraction_metadata.go	Tracking ID validation
15	plugins	1 occurrence	frontmatter_extraction_metadata.go	Plugin configuration extraction
16	if	1 occurrence	frontmatter_extraction_yaml.go	Conditional expression extraction
17	secret-masking	1 occurrence	secret_masking.go	Secret masking configuration
18	mcp-servers	1 occurrence	strict_mode_validation.go	MCP server validation
19	tools	1 occurrence	strict_mode_validation.go	Tools configuration validation
20	github-token	2+ occurrences (test files)	Various token handling tests	GitHub token extraction

Frontmatter Field Access Locations - Non-Test Files

Field	File	Line(s)	Context
on	filters.go	18, 112, 205	Event trigger filtering
on	stop_after.go	26, 172, 251	Workflow scheduling preprocessing
on	role_checks.go	241, 318, 400	Role and permission validation
on	frontmatter_extraction_yaml.go	132, 513	YAML section extraction
on	manual_approval.go	13	Manual approval workflow generation
on	compiler_safe_outputs.go	35	Safe outputs compilation
on	compiler_filters_validation.go	47	Filter validation
on	schedule_preprocessing.go	107, 126, 141, 157, 191	Schedule preprocessing with modification
safe-outputs	safe_outputs_config.go	56, 451	Safe outputs configuration parsing
safe-outputs	safe_jobs.go	300	Safe job validation
safe-inputs	safe_inputs_parser.go	215, 233	Safe input validation
permissions	frontmatter_extraction_yaml.go	448	Permissions YAML extraction
permissions	strict_mode_validation.go	54	Strict mode permission validation
network	frontmatter_extraction_security.go	11	Network permission extraction
sandbox	frontmatter_extraction_security.go	157	Sandbox configuration extraction
engine	engine.go	75	Engine type determination
roles	role_checks.go	92	Role extraction for permission checks
bots	role_checks.go	127	Bot identifier extraction
rate-limit	role_checks.go	156	Rate limit configuration extraction
features	frontmatter_extraction_metadata.go	17	Feature flags extraction
description	frontmatter_extraction_metadata.go	40	Metadata extraction
source	frontmatter_extraction_metadata.go	58	Source URL extraction
tracker-id	frontmatter_extraction_metadata.go	73	Tracker ID validation
plugins	frontmatter_extraction_metadata.go	271	Plugin configuration extraction
if	frontmatter_extraction_yaml.go	480	Conditional expression extraction
secret-masking	secret_masking.go	12	Secret masking configuration
mcp-servers	strict_mode_validation.go	113	MCP server strict mode validation
tools	strict_mode_validation.go	156	Tools strict mode validation

Helper Functions for Field Extraction

File: /home/runner/work/gh-aw/gh-aw/pkg/workflow/frontmatter_types.go

1. ExtractMapField (Line 447-465)

   • Extracts map[string]any fields from frontmatter
   • Returns empty map if key doesn't exist (backward compatibility)
   • Used by: extractToolsFromFrontmatter, extractMCPServersFromFrontmatter, extractRuntimesFromFrontmatter

2. ExtractStringField (Line 469-476)

   • Extracts string fields from frontmatter
   • Returns empty string if conversion fails

3. ExtractIntField (Line 480-487)

   • Extracts integer fields from frontmatter
   • Returns 0 if conversion fails

4. ParseFrontmatterConfig (Line 204-253)

   • Main entry point for converting untyped map[string]any to structured FrontmatterConfig
   • Handles JSON marshaling/unmarshaling for type conversion
   • Calls specialized parsers for complex types

5. parseRuntimesConfig (Line 255-307)

   • Converts map[string]any to RuntimesConfig
   • Maps: node, python, go, uv, bun, deno

6. parsePermissionsConfig (Line 310-367)

   • Converts map[string]any to PermissionsConfig
   • Handles both shorthand (read-all, write-all, etc.) and detailed scope-based permissions

7. parsePluginsConfig (Line 373-412)

   • Parses plugins field supporting both array and object formats

Fields Validated but Not Directly in Struct

The following fields are validated but represent nested or derived data rather than direct struct fields:

Field	Nested In	Validation Location	Type
schedule (cron rules)	on.schedule	schedule_preprocessing.go	Cron expression parsing
draft	on.pull_request	frontmatter_extraction_yaml.go	Draft PR filtering
forks	on.pull_request	frontmatter_extraction_yaml.go	Fork filtering
names	on.*.names	frontmatter_extraction_yaml.go	Label name filtering
manual-approval	top-level on	frontmatter_extraction_yaml.go	Manual approval preprocessing
stop-after	top-level on	frontmatter_extraction_yaml.go	Stop-after preprocessing
skip-if-match	top-level on	frontmatter_extraction_yaml.go	Pre-activation job skip condition
skip-if-no-match	top-level on	frontmatter_extraction_yaml.go	Pre-activation job skip condition
reaction	top-level on	frontmatter_extraction_yaml.go	Reaction trigger preprocessing
lock-for-agent	on.*.lock-for-agent	frontmatter_extraction_yaml.go	Issue locking preprocessing
max	rate-limit.max	role_checks.go (line 162)	Rate limit maximum
window	rate-limit.window	role_checks.go (line 176)	Rate limit window
events	rate-limit.events	role_checks.go (line 190)	Rate limit events filter
ignored-roles	rate-limit.ignored-roles	role_checks.go (line ~210)	Rate limit ignored roles

Constants with "Default" Values

Files with Default Constants:

1. pkg/workflow/runtime_definitions.go

   • DefaultVersion fields in runtime definitions
   • References constants like: DefaultBunVersion, DefaultDenoVersion, DefaultDotNetVersion, DefaultElixirVersion, DefaultGoVersion, DefaultHaskellVersion, DefaultJavaVersion, DefaultNodeVersion, DefaultPythonVersion, DefaultRubyVersion

2. pkg/workflow/mcp_gateway_constants.go

   • DefaultMCPGatewayPort (line 36)

3. pkg/workflow/role_checks.go

   • DefaultRateLimitMax (line 51)
   • DefaultRateLimitWindow (line 58)

4. pkg/workflow/cache.go

   • DefaultAllowedMemoryExtensions (lines 129, 155, 169)

5. pkg/workflow/compiler_safe_outputs.go

   • DefaultBashTools (lines 408-409, 433)

6. pkg/workflow/copilot_sdk_engine.go

   • DefaultCopilotDetectionModel (line 62)

7. pkg/workflow/mcp_config_builtin.go

   • DefaultAlpineImage (lines 191, 312)
   • DefaultWorkspaceMount, DefaultTmpGhAwMount, DefaultGhAwMount, DefaultGhBinaryMount (lines 206, 214, 325, 332)

8. pkg/workflow/claude_engine.go

   • DefaultClaudeCodeVersion (line 79)
   • DefaultMCPStartupTimeout (line 333)
   • DefaultToolTimeout (line 339)
   • DefaultAgenticWorkflowTimeout (lines 427, 146 in tools.go)

9. pkg/workflow/firewall.go

   • DefaultFirewallVersion (line 173)

10. pkg/parser/mcp.go

    • DefaultGitHubMCPServerVersion (line 364)
    • DefaultPlaywrightBrowserVersion (line 443)
    • DefaultAllowedDomains (line 451)

Validation Architecture

Key Validation Files:

1. frontmatter_extraction_*.go - Three specialized extraction files:

   • frontmatter_extraction_metadata.go - Features, description, source, tracker-id, plugins validation
   • frontmatter_extraction_yaml.go - On triggers, permissions, conditions, command config
   • frontmatter_extraction_security.go - Network, sandbox, firewall, MCP gateway configuration

2. strict_mode_validation.go - Strict mode enforcement for production workflows:

   • validateStrictPermissions() - Refuses write permissions on sensitive scopes
   • validateStrictNetwork() - Requires explicit network config, refuses wildcard "*"
   • validateStrictMCPNetwork() - Requires network config for container-based MCP servers
   • validateStrictTools() - Validates serena local mode and cache-memory scope

3. role_checks.go - Role-based access control validation:

   • extractRoles() - Default to ["admin", "maintainer", "write"]
   • extractBots() - Bot identifier extraction
   • extractRateLimitConfig() - Rate limit settings with defaults

Summary Statistics

• Total fields in FrontmatterConfig struct: 48 fields
• Fields directly in JSON (with json tag): 39 fields
• Fields excluded from JSON (json:"-"): 4 fields (RuntimesTyped, PermissionsTyped, PluginsTyped, PluginsRepos, PluginsToken)
• Unique frontmatter keys accessed in code: 28+ distinct keys
• Most frequently accessed field: "on" (18+ times)
• Validation specialization files: 3 dedicated extraction files
• Default value constants: 30+ constants across multiple files

AI generated by Schema Consistency Checker

• expires on Feb 22, 2026, 9:58 AM UTC