Audit of the jobs: sub-object reveals that buildCustomJobs() in pkg/workflow/compiler_jobs.go extracts only 8 of the 17 schema-defined job properties, silently discarding the rest. Users who rely on schema autocomplete to write custom job configurations will see their settings accepted at parse time but silently dropped at compile time with no warning or error.

Strategy used: Strategy-19 — Custom Jobs Compiler Coverage Gap Analysis (variant of Strategy-1 Hybrid Semantic Field Coverage, applied to jobs: sub-object specifically)
Run: §22617702420 · 2026-03-03

Summary

Critical Issues

HIGH-1 — Custom jobs: 7 schema-defined job fields silently dropped by buildCustomJobs()

File: pkg/workflow/compiler_jobs.go · buildCustomJobs() starting at line ~424

The jobs: frontmatter schema (main_workflow_schema.json, .properties.jobs.additionalProperties.properties) defines 17 standard job properties. The buildCustomJobs() compiler function only extracts 8 of them. The remaining 7 are silently dropped — no error, no warning, no hint.

Note: container and services do work at the top-level workflow scope (extracted via extractTopLevelYAMLSection in compiler_orchestrator_workflow.go:236 and :365), but NOT when used inside a named custom job entry. This creates a confusing asymmetry.

// pkg/workflow/compiler_jobs.go ~line 433
job := &Job{
    Name: jobName,  // <-- ID key, NOT the display name field
}

// Only these are extracted:
// needs, runs-on (string only), if, permissions, outputs,
// uses/with/secrets (reusable workflow), steps

// These Job struct fields exist but are NEVER populated for custom jobs:
// job.DisplayName  (from "name:" in YAML)
// job.TimeoutMinutes
// job.Concurrency
// job.Container
// job.Services
// job.Env

if job.DisplayName != "" {
    fmt.Fprintf(&yaml, "    name: %s\n", job.DisplayName)
}

Impact: Users who add timeout-minutes, env, container, services, concurrency, name, or continue-on-error to their custom job definitions get no indication these are unsupported — the schema validates them, the compiler silently discards them.

HIGH-2 — Custom jobs runs-on array and object forms silently dropped

File: pkg/workflow/compiler_jobs.go:465-469

The schema defines runs-on for custom jobs as a oneOf [string, array, object]:

"runs-on": {
  "oneOf": [
    { "type": "string" },
    { "type": "array", "items": { "type": "string" } },
    { "type": "object", "additionalProperties": false }
  ]
}

The compiler only handles the string variant:

if runsOn, hasRunsOn := configMap["runs-on"]; hasRunsOn {
    if runsOnStr, ok := runsOn.(string); ok {
        job.RunsOn = "runs-on: " + runsOnStr
    }
    // array/object: falls through silently, job.RunsOn stays ""
}

When runs-on is an array (e.g., [self-hosted, linux, large]), the type assertion runsOn.(string) fails, job.RunsOn remains empty, and the compiled job is emitted without a runs-on field — which is invalid GitHub Actions YAML.

Contrast: The top-level runs-on uses extractTopLevelYAMLSection (compiler_orchestrator_workflow.go:234) which passes the raw YAML through correctly for all three forms.

Impact: Custom jobs using runner arrays (common for self-hosted or larger runners) produce malformed compiled output with no error.

Schema Improvements Needed

MEDIUM-1 — cache-memory scope enum value not validated in code

File: pkg/workflow/cache.go:106-110

The schema defines scope as an enum:

"scope": {
  "type": "string",
  "enum": ["workflow", "repo"],
  "default": "workflow"
}

The parser code accepts any string with no validation:

if scope, exists := cacheMap["scope"]; exists {
    if scopeStr, ok := scope.(string); ok {
        entry.Scope = scopeStr  // no enum check here
    }
}

Later logic only tests if scope == "repo" (cache.go:406), so any invalid value (e.g., "organization", "global") silently falls through to "workflow" behavior. Users get no feedback that their scope setting is invalid.

Impact: Invalid scope values pass schema validation (if schema validation is skipped) and are silently treated as "workflow", creating confusing debugging scenarios.

MEDIUM-2 — jobs.strategy schema is structurally unusable

File: pkg/parser/schemas/main_workflow_schema.json, .properties.jobs.additionalProperties.properties.strategy

"strategy": {
  "type": "object",
  "description": "Matrix strategy for the job",
  "additionalProperties": false
}

This defines strategy as an empty object — additionalProperties: false with no properties — meaning the only valid value is {}. Any real GitHub Actions matrix strategy (e.g., matrix: {os: [ubuntu, windows]}) would fail schema validation.

The schema includes the field to signal "this is a GitHub Actions job," but the definition actively blocks valid usage and provides no useful structure. The compiler also does not extract or pass through strategy at all.

Options:

1. Remove strategy from the schema (honest: not supported in custom jobs)
2. Define it with proper matrix/include/exclude/fail-fast/max-parallel properties (implement support)
3. Use additionalProperties: true to allow pass-through without explicit support (pragmatic workaround)

Documentation Gaps

MEDIUM-3 — Custom jobs section over-promises support

File: docs/src/content/docs/reference/frontmatter.md:609

The custom jobs section says:

"Supports complete GitHub Actions step specification."

This refers to steps (not jobs), but the phrasing is adjacent to the job definition examples and could mislead users into thinking all GitHub Actions job properties work in custom jobs. There is no documentation of:

• Which job-level fields actually work (the 9 listed in HIGH-1)
• Which fields are silently ignored (timeout-minutes, env, container, services, concurrency, name, continue-on-error)
• The fact that runs-on only supports string form

Suggested addition: A table or note listing supported vs unsupported job fields, similar to the runner support table at line 465.

Recommendations

1. Fix buildCustomJobs() to extract the missing fields — env, timeout-minutes, concurrency, name/DisplayName are straightforward additions since the Job struct already has the fields and the rendering code in jobs.go already handles them. container and services require YAML string conversion (same pattern as top-level extraction). continue-on-error needs a new Job struct field.

2. Fix runs-on array/object handling in buildCustomJobs() — Use go-yaml.Marshal on the raw value (matching the top-level approach) instead of a type-asserting string cast. Prevents malformed output for self-hosted runner arrays.

3. Add scope enum validation in parseCacheMemoryEntry() — After parsing the scope string, validate it against ["workflow", "repo"] and return an error for invalid values.

4. Fix or remove strategy schema definition — Either define it properly with all GitHub Actions strategy sub-fields, or remove it to avoid false promises.

5. Update custom jobs documentation — Add a clear field support table documenting which job-level properties are supported.

Strategy Performance

• Strategy used: Strategy-19 (Custom Jobs Compiler Coverage Gap Analysis — variant of Strategy-1 applied to jobs: sub-object)
• Findings: 5 (2 High, 3 Medium)
• Effectiveness: HIGH — all findings have direct user impact (silent data loss, malformed compiled output)
• Should reuse: YES — applying field coverage analysis to individual sub-objects continues to yield actionable bugs

References:

• §22617702420

AI generated by Schema Consistency Checker · history

• expires on Mar 4, 2026, 10:09 AM UTC