Objective
Update the custom jobs documentation in docs/src/content/docs/reference/frontmatter.md to accurately document which job-level properties are supported vs unsupported.
Context
From discussion #19383 (MEDIUM-3): The custom jobs section (around line 609) currently states:
"Supports complete GitHub Actions step specification."
This is misleading — it applies to steps, not jobs, but is adjacent to job definition examples and implies full job property support. There is no documentation of which job-level fields work and which are silently dropped.
After fixes from the other sub-issues, the supported field set will be:
- Supported:
needs, runs-on (string, array, object), if, permissions, outputs, uses, with, secrets, steps, name, timeout-minutes, concurrency, env, container, services, continue-on-error
- Not supported:
strategy (removed from schema)
Approach
In docs/src/content/docs/reference/frontmatter.md, in the custom jobs section:
- Replace or clarify the "Supports complete GitHub Actions step specification" sentence to make clear it refers to steps
- Add a table or note listing supported job-level fields and any unsupported fields
- Note that
runs-on supports string, array, and object forms
- Add a brief example showing a custom job with
timeout-minutes and env
Files to Modify
docs/src/content/docs/reference/frontmatter.md — update custom jobs section (~line 609)
Acceptance Criteria
Generated by Plan Command for issue #discussion #19383 · ◷
Objective
Update the custom jobs documentation in
docs/src/content/docs/reference/frontmatter.mdto accurately document which job-level properties are supported vs unsupported.Context
From discussion #19383 (MEDIUM-3): The custom jobs section (around line 609) currently states:
This is misleading — it applies to steps, not jobs, but is adjacent to job definition examples and implies full job property support. There is no documentation of which job-level fields work and which are silently dropped.
After fixes from the other sub-issues, the supported field set will be:
needs,runs-on(string, array, object),if,permissions,outputs,uses,with,secrets,steps,name,timeout-minutes,concurrency,env,container,services,continue-on-errorstrategy(removed from schema)Approach
In
docs/src/content/docs/reference/frontmatter.md, in the custom jobs section:runs-onsupports string, array, and object formstimeout-minutesandenvFiles to Modify
docs/src/content/docs/reference/frontmatter.md— update custom jobs section (~line 609)Acceptance Criteria
runs-onforms (string, array, object) are documentedtimeout-minutesandenvmake agent-finishbefore committing (docs changes don't need build/test but validate formatting)