[awf-feature-surfacing] Surface jobs.(job).setup-steps in .github/aw/ syntax docs + setup-steps vs pre-steps guidance

[github-actions]

Summary

A new AWF spec/compiler capability — jobs.<job>.setup-steps (#37368) — lets workflow authors inject their own steps before the framework mints a GitHub App token (actions/create-github-app-token) and before checkout, in both built-in jobs (agent, safe_outputs, conclusion, detection, unlock, activation, pre_activation) and custom jobs. This enables OIDC login, dynamic secret fetching, and credential bootstrap prior to token minting — previously only the agent job had a practical pre-token hook.

It is a sibling of the existing jobs.<job>.pre-steps hook (setup-steps runs earlier — before token-mint/checkout; pre-steps runs after compiler setup, before checkout/steps).

The feature is fully documented on the docs site, but is not surfaced in the .github/aw/ agentic-workflow context docs, where its sibling pre-steps already is. This is the actionable gap.

New feature(s)

Feature	Schema key	What it enables
Pre-token setup hook	jobs.<job>.setup-steps	Run OIDC / secret-fetch / credential bootstrap steps before framework GitHub App token minting and checkout, in built-in and custom jobs

Current surfacing status

Surface	Status
pkg/parser/schemas/main_workflow_schema.json	✅ property + validation added
docs/src/.../reference/steps-jobs.md	✅ full injection-order tables, import-merge semantics, setup-steps vs pre-steps
docs/src/.../reference/glossary.md	✅ entry added
docs/adr/37368-*.md	✅ Draft ADR
.github/aw/syntax-core.md	❌ documents pre-steps/pre-agent-steps/post-steps only — no setup-steps
.github/aw/syntax-agentic.md	❌ documents custom/built-in job pre-steps (line ~248) — no setup-steps
.github/aw/workflow-constraints.md	❌ no setup-steps guidance

(The only setup-steps matches in .github/aw/ are the unrelated copilot-setup-steps.yml import feature.)

The ADR itself flags the risk: "Two closely related concepts (setup-steps and pre-steps) now coexist, which can confuse authors about which to use." — strengthening the case for explicit .github/aw/ guidance.

Evidence

Schema diff (only schema change in the review window)

"setup-steps": {
  "allOf": [{ "$ref": "#/properties/jobs/additionalProperties/properties/steps" }],
  "description": "Optional setup steps inserted after setup-injected steps and before any token-mint or checkout steps in this job. Uses the same schema as steps."
}

Source

• Commit 78ebc77fd — "Add jobs.<job>.setup-steps and inject before compiler setup and App token minting (Add jobs.<job>.setup-steps and inject before compiler setup and App token minting #37368)"
• Schema: pkg/parser/schemas/main_workflow_schema.json
• Compiler: pkg/workflow/compiler_jobs.go, safe_outputs_jobs.go, workflow_import_merge.go, compiler_activation_job_builder.go
• Feature id: jobs-setup-steps

Follow-up tasks

• [High] Add jobs.<job>.setup-steps to .github/aw/syntax-agentic.md alongside the existing custom/built-in job pre-steps entry, describing the pre-token-mint injection point and the per-job ordering.
• [High] Add a short "setup-steps vs pre-steps — which to use" note (setup-steps = before App token minting / OIDC / secret-fetch; pre-steps = after compiler setup, before checkout) to .github/aw/syntax-core.md and/or syntax-agentic.md to address the ADR-flagged confusion.
• [Medium] Mention setup-steps import-merge semantics (imported first, then main; kept separate from pre-steps) in .github/aw/syntax-tools-imports.md / reuse.md.
• [Low] Confirm whether any upgrade/migration guidance is warranted (likely none — additive/backward-compatible); note explicitly if not.
• [Low] Verify a docs example exists showing OIDC/secret bootstrap via setup-steps in a built-in job.

Out of scope / excluded this run

• --gh-aw-ref compile CLI flag (feat(cli): add --gh-aw-ref convenience flag to compile #37313) — CLI convenience, not an AWF spec change.
• max-effective-tokens migration snippet (Remove symbol from model alias, clarify AIC in ET table title, add max-effective-tokens migration snippet #37387) — guidance only.
• Copilot SDK bash-parser permission semantics — internal engine behavior, not user-facing spec.

Generated by 🧭 Daily AWF Spec Compiler Surfacing Review · 121.7 AIC · ⌖ 12 AIC · ⊞ 4.8K · ◷

• expires on Jun 13, 2026, 10:40 PM UTC