From 0e6b863a6ef12fc96e5128a8d977091c1347f2d7 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 6 Jun 2026 22:43:34 +0000
Subject: [PATCH 01/13] Initial plan


From 5fa37754ad60e346f1dab141f836deac7f447694 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 6 Jun 2026 22:53:17 +0000
Subject: [PATCH 02/13] docs(aw): surface jobs setup-steps and clarify
 setup-vs-pre guidance

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/aw/reuse.md                |  3 ++-
 .github/aw/syntax-agentic.md       | 24 ++++++++++++++++++++++++
 .github/aw/syntax-core.md          |  2 ++
 .github/aw/syntax-tools-imports.md |  3 ++-
 .github/aw/workflow-constraints.md |  1 +
 5 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/.github/aw/reuse.md b/.github/aw/reuse.md
index 55f37ec7a89..609b66dfe2b 100644
--- a/.github/aw/reuse.md
+++ b/.github/aw/reuse.md
@@ -17,7 +17,8 @@ Only these frontmatter fields are merged when a file is imported:
 | `tools:`, `mcp-servers:`, `safe-outputs:`, `network:`, `permissions:`, `runtimes:`, `services:`, `cache:`, `features:` | Deep-merged |
 | `env:` | Merged; duplicate keys → compile error |
 | `github-app:`, `on.github-app:` | First-wins across imports |
-| `steps:`, `pre-steps:`, `pre-agent-steps:`, `post-steps:` | Appended in import order |
+| `steps:`, `pre-agent-steps:`, `post-steps:` | Appended in import order |
+| `jobs.<job-id>.setup-steps`, `jobs.<job-id>.pre-steps` | For each job, imported steps run first, then main workflow steps; `setup-steps` remains separate from `pre-steps` |
 | Markdown body | Appended as prompt instructions |
 
 All other fields (`on:`, `engine:`, `timeout-minutes:`, …) are ignored in imported files.
diff --git a/.github/aw/syntax-agentic.md b/.github/aw/syntax-agentic.md
index 32a286c1210..ae43f0e06a1 100644
--- a/.github/aw/syntax-agentic.md
+++ b/.github/aw/syntax-agentic.md
@@ -245,13 +245,18 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
   - Each job can have: `name`, `runs-on`, `steps`, `needs`, `if`, `env`, `permissions`, `timeout-minutes`, etc.
   - For most agentic workflows, jobs are auto-generated; only specify this for advanced multi-job workflows
   - **Security Notice**: Custom jobs run OUTSIDE the firewall sandbox. Execute with standard GitHub Actions security but NO network egress controls. Use only for deterministic preprocessing, data fetching, or static analysis—not agentic compute or untrusted AI execution.
+  - **`setup-steps:`** - Steps injected before compiler-generated setup, GitHub App token minting, and checkout in a custom or built-in job (array). Use this for OIDC login, secret fetch, and credential bootstrap that must happen before framework token/checkout steps. Imported `setup-steps` run before main workflow `setup-steps`.
   - **`pre-steps:`** - Steps injected after compiler-generated setup and before any `steps:` in a custom or built-in job (array). For built-in jobs (`activation`, `pre_activation`), injected after the `id: setup` step and before the first checkout. Imported `pre-steps` run before main workflow `pre-steps`.
+  - **`setup-steps` vs `pre-steps`** - Use `setup-steps` for pre-token bootstrap work (OIDC/secret retrieval). Use `pre-steps` for steps that should run after compiler setup but before main job work.
   - Example:
 
     ```yaml
     jobs:
       custom-job:
         runs-on: ubuntu-latest
+        setup-steps:
+          - name: Bootstrap credentials
+            run: echo "runs before framework token/checkout setup"
         pre-steps:
           - name: Pre-flight setup
             run: echo "runs before checkout"
@@ -260,6 +265,25 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
             run: echo "Custom job"
     ```
 
+  - Built-in job example (OIDC/secret bootstrap before token minting):
+
+    ```yaml
+    jobs:
+      activation:
+        setup-steps:
+          - name: Configure cloud credentials with OIDC
+            uses: aws-actions/configure-aws-credentials@v4
+            with:
+              role-to-assume: arn:aws:iam::123456789012:role/gh-aw-activation
+              aws-region: us-east-1
+          - name: Fetch bootstrap token
+            id: bootstrap
+            run: echo "token=fetched-value" >> "$GITHUB_OUTPUT"
+        pre-steps:
+          - name: Verify bootstrap token
+            run: test -n "${{ steps.bootstrap.outputs.token }}"
+    ```
+
 - **`engine:`** - AI processor configuration
   - String format: `"copilot"` (default, recommended), `"claude"`, `"codex"`, `"gemini"`, or `"opencode"` (experimental)
   - Object format for extended configuration:
diff --git a/.github/aw/syntax-core.md b/.github/aw/syntax-core.md
index 3e899784b97..55601f3d354 100644
--- a/.github/aw/syntax-core.md
+++ b/.github/aw/syntax-core.md
@@ -138,6 +138,8 @@ The YAML frontmatter supports these fields:
 - **`steps:`** - Custom workflow steps before AI execution (object). **Security Notice**: Custom steps run OUTSIDE the firewall sandbox with standard GitHub Actions security but NO network egress controls. Use only for deterministic data preparation, not agentic compute. **Secrets restriction**: Using `${{ secrets.* }}` expressions (other than `secrets.GITHUB_TOKEN`) in custom steps is an error in strict mode and a warning otherwise — move secret-dependent operations to a separate job outside the agent job.
 - **`pre-agent-steps:`** - Custom workflow steps to run before MCP gateway startup (object or array). Use when preparation must install or configure MCP dependencies before the gateway starts. Same security restrictions apply as for `steps:`.
 - **`post-steps:`** - Custom workflow steps after AI execution (object). **Security Notice**: Post-execution steps run OUTSIDE the firewall sandbox. Use only for deterministic cleanup, artifact uploads, or notifications—not agentic compute or untrusted AI execution. Same secrets restriction applies as for `steps:`.
+
+For job-scoped hooks under `jobs.<job-id>`, choose based on timing: `setup-steps` run before framework GitHub App token minting and checkout, while `pre-steps` run after compiler setup and before the job's main work.
 - **`environment:`** - Environment that the job references for protection rules (string or object)
 - **`container:`** - Container to run job steps in (string or object)
 - **`services:`** - Service containers that run alongside the job (object)
diff --git a/.github/aw/syntax-tools-imports.md b/.github/aw/syntax-tools-imports.md
index 1c27a7efddf..dff45bfaf87 100644
--- a/.github/aw/syntax-tools-imports.md
+++ b/.github/aw/syntax-tools-imports.md
@@ -269,7 +269,8 @@ The following frontmatter fields in imported files are merged into the importing
 - `checkout:` - Checkout configurations appended (main workflow's checkouts take precedence)
 - `github-app:` - Top-level GitHub App credentials (first-wins across imports)
 - `on.github-app:` - Activation GitHub App credentials (first-wins across imports)
-- `steps:`, `pre-steps:`, `pre-agent-steps:`, `post-steps:` - Steps appended in import order
+- `steps:`, `pre-agent-steps:`, `post-steps:` - Steps appended in import order
+- `jobs.<job-id>.setup-steps` and `jobs.<job-id>.pre-steps` - Merged per job with imported steps first, then main workflow steps. `setup-steps` remains distinct from `pre-steps` and runs earlier in job execution.
 - `runtimes:`, `network:`, `permissions:`, `services:`, `cache:`, `features:`, `mcp-servers:`
 
 Example import file:
diff --git a/.github/aw/workflow-constraints.md b/.github/aw/workflow-constraints.md
index e5aa56825ad..526a6532be1 100644
--- a/.github/aw/workflow-constraints.md
+++ b/.github/aw/workflow-constraints.md
@@ -62,6 +62,7 @@ When a requested feature increases risk:
 - auto-merge or bypassing review
 - overly broad network access
 - unbounded bash allowlists for untrusted input
+- placing OIDC/secret bootstrap in `pre-steps` instead of earlier `setup-steps`
 - using `post-steps:` for agent-driven write actions
 
 ## Self-Hosted Runner Compatibility

From 0ad166bdb9eb040436e986a0a1582c9a41b71fb5 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 6 Jun 2026 22:54:24 +0000
Subject: [PATCH 03/13] docs(aw): refine setup-steps guidance wording and
 import notes

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/aw/syntax-agentic.md       | 2 +-
 .github/aw/syntax-core.md          | 3 +--
 .github/aw/syntax-tools-imports.md | 3 ++-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/aw/syntax-agentic.md b/.github/aw/syntax-agentic.md
index ae43f0e06a1..e5bba4cb79b 100644
--- a/.github/aw/syntax-agentic.md
+++ b/.github/aw/syntax-agentic.md
@@ -247,7 +247,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
   - **Security Notice**: Custom jobs run OUTSIDE the firewall sandbox. Execute with standard GitHub Actions security but NO network egress controls. Use only for deterministic preprocessing, data fetching, or static analysis—not agentic compute or untrusted AI execution.
   - **`setup-steps:`** - Steps injected before compiler-generated setup, GitHub App token minting, and checkout in a custom or built-in job (array). Use this for OIDC login, secret fetch, and credential bootstrap that must happen before framework token/checkout steps. Imported `setup-steps` run before main workflow `setup-steps`.
   - **`pre-steps:`** - Steps injected after compiler-generated setup and before any `steps:` in a custom or built-in job (array). For built-in jobs (`activation`, `pre_activation`), injected after the `id: setup` step and before the first checkout. Imported `pre-steps` run before main workflow `pre-steps`.
-  - **`setup-steps` vs `pre-steps`** - Use `setup-steps` for pre-token bootstrap work (OIDC/secret retrieval). Use `pre-steps` for steps that should run after compiler setup but before main job work.
+  - **`setup-steps` vs `pre-steps`** - Use `setup-steps` for work that must run before framework GitHub App token minting and checkout (for example OIDC/secret bootstrap). Use `pre-steps` for work that should run after compiler-generated setup and before the job's main `steps:`.
   - Example:
 
     ```yaml
diff --git a/.github/aw/syntax-core.md b/.github/aw/syntax-core.md
index 55601f3d354..0982c2aa44d 100644
--- a/.github/aw/syntax-core.md
+++ b/.github/aw/syntax-core.md
@@ -135,11 +135,10 @@ The YAML frontmatter supports these fields:
 - **`run-name:`** - Custom workflow run name (string)
 - **`name:`** - Workflow name (string)
 - **`pre-steps:`** - Custom workflow steps to run at the very beginning of the agent job, before checkout (object). Use for token minting or setup that must happen before the repository is checked out. Step outputs are available via `${{ steps.<id>.outputs.<name> }}` and can be referenced in `checkout.github-token` to avoid masked-value cross-job boundary issues. Same security restrictions apply as for `steps:`.
+  - For job-scoped hooks under `jobs.<job-id>`, `setup-steps` run before framework GitHub App token minting and checkout, while `pre-steps` run after compiler setup and before the job's main steps.
 - **`steps:`** - Custom workflow steps before AI execution (object). **Security Notice**: Custom steps run OUTSIDE the firewall sandbox with standard GitHub Actions security but NO network egress controls. Use only for deterministic data preparation, not agentic compute. **Secrets restriction**: Using `${{ secrets.* }}` expressions (other than `secrets.GITHUB_TOKEN`) in custom steps is an error in strict mode and a warning otherwise — move secret-dependent operations to a separate job outside the agent job.
 - **`pre-agent-steps:`** - Custom workflow steps to run before MCP gateway startup (object or array). Use when preparation must install or configure MCP dependencies before the gateway starts. Same security restrictions apply as for `steps:`.
 - **`post-steps:`** - Custom workflow steps after AI execution (object). **Security Notice**: Post-execution steps run OUTSIDE the firewall sandbox. Use only for deterministic cleanup, artifact uploads, or notifications—not agentic compute or untrusted AI execution. Same secrets restriction applies as for `steps:`.
-
-For job-scoped hooks under `jobs.<job-id>`, choose based on timing: `setup-steps` run before framework GitHub App token minting and checkout, while `pre-steps` run after compiler setup and before the job's main work.
 - **`environment:`** - Environment that the job references for protection rules (string or object)
 - **`container:`** - Container to run job steps in (string or object)
 - **`services:`** - Service containers that run alongside the job (object)
diff --git a/.github/aw/syntax-tools-imports.md b/.github/aw/syntax-tools-imports.md
index dff45bfaf87..f76df57ea8f 100644
--- a/.github/aw/syntax-tools-imports.md
+++ b/.github/aw/syntax-tools-imports.md
@@ -270,7 +270,8 @@ The following frontmatter fields in imported files are merged into the importing
 - `github-app:` - Top-level GitHub App credentials (first-wins across imports)
 - `on.github-app:` - Activation GitHub App credentials (first-wins across imports)
 - `steps:`, `pre-agent-steps:`, `post-steps:` - Steps appended in import order
-- `jobs.<job-id>.setup-steps` and `jobs.<job-id>.pre-steps` - Merged per job with imported steps first, then main workflow steps. `setup-steps` remains distinct from `pre-steps` and runs earlier in job execution.
+- `jobs.<job-id>.setup-steps` and `jobs.<job-id>.pre-steps` - Merged per job with imported steps first, then main workflow steps.
+- `jobs.<job-id>.setup-steps` runs before `jobs.<job-id>.pre-steps`; the two hooks remain distinct.
 - `runtimes:`, `network:`, `permissions:`, `services:`, `cache:`, `features:`, `mcp-servers:`
 
 Example import file:

From 84abeeb474219dc3ad4f261d0835feefd61a3139 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 6 Jun 2026 22:55:14 +0000
Subject: [PATCH 04/13] docs(aw): add setup-steps migration note

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/aw/syntax-agentic.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/aw/syntax-agentic.md b/.github/aw/syntax-agentic.md
index e5bba4cb79b..67106fb2080 100644
--- a/.github/aw/syntax-agentic.md
+++ b/.github/aw/syntax-agentic.md
@@ -248,6 +248,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
   - **`setup-steps:`** - Steps injected before compiler-generated setup, GitHub App token minting, and checkout in a custom or built-in job (array). Use this for OIDC login, secret fetch, and credential bootstrap that must happen before framework token/checkout steps. Imported `setup-steps` run before main workflow `setup-steps`.
   - **`pre-steps:`** - Steps injected after compiler-generated setup and before any `steps:` in a custom or built-in job (array). For built-in jobs (`activation`, `pre_activation`), injected after the `id: setup` step and before the first checkout. Imported `pre-steps` run before main workflow `pre-steps`.
   - **`setup-steps` vs `pre-steps`** - Use `setup-steps` for work that must run before framework GitHub App token minting and checkout (for example OIDC/secret bootstrap). Use `pre-steps` for work that should run after compiler-generated setup and before the job's main `steps:`.
+  - **Migration note** - No migration is required. `setup-steps` is additive; existing workflows that only use `pre-steps` continue to behave as before.
   - Example:
 
     ```yaml

From 88debe9d78ca393c1f3f28cd18bf2bb93db84947 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 6 Jun 2026 22:56:13 +0000
Subject: [PATCH 05/13] docs(aw): clarify setup-steps and pre-steps sequencing

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/aw/syntax-agentic.md       | 6 +++---
 .github/aw/syntax-tools-imports.md | 3 +--
 2 files changed, 4 insertions(+), 5 deletions(-)

diff --git a/.github/aw/syntax-agentic.md b/.github/aw/syntax-agentic.md
index 67106fb2080..ee55cdc8891 100644
--- a/.github/aw/syntax-agentic.md
+++ b/.github/aw/syntax-agentic.md
@@ -245,9 +245,9 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
   - Each job can have: `name`, `runs-on`, `steps`, `needs`, `if`, `env`, `permissions`, `timeout-minutes`, etc.
   - For most agentic workflows, jobs are auto-generated; only specify this for advanced multi-job workflows
   - **Security Notice**: Custom jobs run OUTSIDE the firewall sandbox. Execute with standard GitHub Actions security but NO network egress controls. Use only for deterministic preprocessing, data fetching, or static analysis—not agentic compute or untrusted AI execution.
-  - **`setup-steps:`** - Steps injected before compiler-generated setup, GitHub App token minting, and checkout in a custom or built-in job (array). Use this for OIDC login, secret fetch, and credential bootstrap that must happen before framework token/checkout steps. Imported `setup-steps` run before main workflow `setup-steps`.
-  - **`pre-steps:`** - Steps injected after compiler-generated setup and before any `steps:` in a custom or built-in job (array). For built-in jobs (`activation`, `pre_activation`), injected after the `id: setup` step and before the first checkout. Imported `pre-steps` run before main workflow `pre-steps`.
-  - **`setup-steps` vs `pre-steps`** - Use `setup-steps` for work that must run before framework GitHub App token minting and checkout (for example OIDC/secret bootstrap). Use `pre-steps` for work that should run after compiler-generated setup and before the job's main `steps:`.
+  - **`setup-steps:`** - Steps injected at the earliest point in a custom or built-in job, before framework GitHub App token minting and before checkout (array). Use this for OIDC login, secret fetch, and credential bootstrap that must happen before framework token/checkout steps. Imported `setup-steps` run before main workflow `setup-steps`.
+  - **`pre-steps:`** - Steps injected after job setup scaffolding and before the job's main `steps:` in a custom or built-in job (array). For built-in jobs (`activation`, `pre_activation`), injected after the `id: setup` step and before the first checkout. Imported `pre-steps` run before main workflow `pre-steps`.
+  - **`setup-steps` vs `pre-steps`** - Use `setup-steps` for work that must run before framework GitHub App token minting and checkout (for example OIDC/secret bootstrap). Use `pre-steps` for work that should run later, after setup scaffolding and before the job's main `steps:`.
   - **Migration note** - No migration is required. `setup-steps` is additive; existing workflows that only use `pre-steps` continue to behave as before.
   - Example:
 
diff --git a/.github/aw/syntax-tools-imports.md b/.github/aw/syntax-tools-imports.md
index f76df57ea8f..bb0ed118ac2 100644
--- a/.github/aw/syntax-tools-imports.md
+++ b/.github/aw/syntax-tools-imports.md
@@ -270,8 +270,7 @@ The following frontmatter fields in imported files are merged into the importing
 - `github-app:` - Top-level GitHub App credentials (first-wins across imports)
 - `on.github-app:` - Activation GitHub App credentials (first-wins across imports)
 - `steps:`, `pre-agent-steps:`, `post-steps:` - Steps appended in import order
-- `jobs.<job-id>.setup-steps` and `jobs.<job-id>.pre-steps` - Merged per job with imported steps first, then main workflow steps.
-- `jobs.<job-id>.setup-steps` runs before `jobs.<job-id>.pre-steps`; the two hooks remain distinct.
+- `jobs.<job-id>.setup-steps` and `jobs.<job-id>.pre-steps` - Merged per job with imported steps first, then main workflow steps; `setup-steps` remains distinct and executes before `pre-steps`.
 - `runtimes:`, `network:`, `permissions:`, `services:`, `cache:`, `features:`, `mcp-servers:`
 
 Example import file:

From 37728339c813066f532fa48b565a7a1d90a26765 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 6 Jun 2026 22:57:07 +0000
Subject: [PATCH 06/13] docs(aw): split import hook semantics for clarity

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/aw/syntax-agentic.md       | 2 +-
 .github/aw/syntax-tools-imports.md | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/.github/aw/syntax-agentic.md b/.github/aw/syntax-agentic.md
index ee55cdc8891..aba4ee345a1 100644
--- a/.github/aw/syntax-agentic.md
+++ b/.github/aw/syntax-agentic.md
@@ -247,7 +247,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
   - **Security Notice**: Custom jobs run OUTSIDE the firewall sandbox. Execute with standard GitHub Actions security but NO network egress controls. Use only for deterministic preprocessing, data fetching, or static analysis—not agentic compute or untrusted AI execution.
   - **`setup-steps:`** - Steps injected at the earliest point in a custom or built-in job, before framework GitHub App token minting and before checkout (array). Use this for OIDC login, secret fetch, and credential bootstrap that must happen before framework token/checkout steps. Imported `setup-steps` run before main workflow `setup-steps`.
   - **`pre-steps:`** - Steps injected after job setup scaffolding and before the job's main `steps:` in a custom or built-in job (array). For built-in jobs (`activation`, `pre_activation`), injected after the `id: setup` step and before the first checkout. Imported `pre-steps` run before main workflow `pre-steps`.
-  - **`setup-steps` vs `pre-steps`** - Use `setup-steps` for work that must run before framework GitHub App token minting and checkout (for example OIDC/secret bootstrap). Use `pre-steps` for work that should run later, after setup scaffolding and before the job's main `steps:`.
+  - **`setup-steps` vs `pre-steps`** - Use `setup-steps` for work that must run before framework GitHub App token minting and checkout (e.g., OIDC/secret bootstrap). Use `pre-steps` for work that should run later, after setup scaffolding and before the job's main `steps:`.
   - **Migration note** - No migration is required. `setup-steps` is additive; existing workflows that only use `pre-steps` continue to behave as before.
   - Example:
 
diff --git a/.github/aw/syntax-tools-imports.md b/.github/aw/syntax-tools-imports.md
index bb0ed118ac2..386e354709c 100644
--- a/.github/aw/syntax-tools-imports.md
+++ b/.github/aw/syntax-tools-imports.md
@@ -270,7 +270,8 @@ The following frontmatter fields in imported files are merged into the importing
 - `github-app:` - Top-level GitHub App credentials (first-wins across imports)
 - `on.github-app:` - Activation GitHub App credentials (first-wins across imports)
 - `steps:`, `pre-agent-steps:`, `post-steps:` - Steps appended in import order
-- `jobs.<job-id>.setup-steps` and `jobs.<job-id>.pre-steps` - Merged per job with imported steps first, then main workflow steps; `setup-steps` remains distinct and executes before `pre-steps`.
+- `jobs.<job-id>.setup-steps` and `jobs.<job-id>.pre-steps` - Merged per job with imported steps first, then main workflow steps.
+- Job hook execution order remains: `setup-steps` runs before `pre-steps`.
 - `runtimes:`, `network:`, `permissions:`, `services:`, `cache:`, `features:`, `mcp-servers:`
 
 Example import file:

From 060560d818f4ee9eb5947a9e512d10c913fe7fd4 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 6 Jun 2026 22:57:57 +0000
Subject: [PATCH 07/13] docs(aw): clarify placeholder token fetch example

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/aw/syntax-agentic.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/aw/syntax-agentic.md b/.github/aw/syntax-agentic.md
index aba4ee345a1..ddc3ea0dfe6 100644
--- a/.github/aw/syntax-agentic.md
+++ b/.github/aw/syntax-agentic.md
@@ -266,7 +266,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
             run: echo "Custom job"
     ```
 
-  - Built-in job example (OIDC/secret bootstrap before token minting):
+  - Built-in job example (OIDC/secret bootstrap before token minting). Replace the placeholder fetch command with your real secret manager/API call:
 
     ```yaml
     jobs:

From b5ba6dd85855c8ce45a49bc1fb893492c6ca63c9 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 6 Jun 2026 22:58:49 +0000
Subject: [PATCH 08/13] docs(aw): polish setup-steps wording consistency

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/aw/syntax-agentic.md       | 1 +
 .github/aw/syntax-tools-imports.md | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/aw/syntax-agentic.md b/.github/aw/syntax-agentic.md
index ddc3ea0dfe6..14544753626 100644
--- a/.github/aw/syntax-agentic.md
+++ b/.github/aw/syntax-agentic.md
@@ -279,6 +279,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
               aws-region: us-east-1
           - name: Fetch bootstrap token
             id: bootstrap
+            # Example placeholder; replace with a real secret manager/API call.
             run: echo "token=fetched-value" >> "$GITHUB_OUTPUT"
         pre-steps:
           - name: Verify bootstrap token
diff --git a/.github/aw/syntax-tools-imports.md b/.github/aw/syntax-tools-imports.md
index 386e354709c..ce109d89f65 100644
--- a/.github/aw/syntax-tools-imports.md
+++ b/.github/aw/syntax-tools-imports.md
@@ -271,7 +271,7 @@ The following frontmatter fields in imported files are merged into the importing
 - `on.github-app:` - Activation GitHub App credentials (first-wins across imports)
 - `steps:`, `pre-agent-steps:`, `post-steps:` - Steps appended in import order
 - `jobs.<job-id>.setup-steps` and `jobs.<job-id>.pre-steps` - Merged per job with imported steps first, then main workflow steps.
-- Job hook execution order remains: `setup-steps` runs before `pre-steps`.
+- Job hook execution order remains: `jobs.<job-id>.setup-steps` runs before `jobs.<job-id>.pre-steps`.
 - `runtimes:`, `network:`, `permissions:`, `services:`, `cache:`, `features:`, `mcp-servers:`
 
 Example import file:

From e2e1d485440144df0124ae36249507125f1025b9 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 6 Jun 2026 22:59:42 +0000
Subject: [PATCH 09/13] docs(aw): improve setup-steps examples and list
 formatting

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/aw/syntax-agentic.md       | 1 +
 .github/aw/syntax-tools-imports.md | 4 +++-
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/.github/aw/syntax-agentic.md b/.github/aw/syntax-agentic.md
index 14544753626..e5dbf66ce3f 100644
--- a/.github/aw/syntax-agentic.md
+++ b/.github/aw/syntax-agentic.md
@@ -275,6 +275,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
           - name: Configure cloud credentials with OIDC
             uses: aws-actions/configure-aws-credentials@v4
             with:
+              # Replace with your AWS account role ARN.
               role-to-assume: arn:aws:iam::123456789012:role/gh-aw-activation
               aws-region: us-east-1
           - name: Fetch bootstrap token
diff --git a/.github/aw/syntax-tools-imports.md b/.github/aw/syntax-tools-imports.md
index ce109d89f65..a9498584afc 100644
--- a/.github/aw/syntax-tools-imports.md
+++ b/.github/aw/syntax-tools-imports.md
@@ -269,7 +269,9 @@ The following frontmatter fields in imported files are merged into the importing
 - `checkout:` - Checkout configurations appended (main workflow's checkouts take precedence)
 - `github-app:` - Top-level GitHub App credentials (first-wins across imports)
 - `on.github-app:` - Activation GitHub App credentials (first-wins across imports)
-- `steps:`, `pre-agent-steps:`, `post-steps:` - Steps appended in import order
+- `steps:` - Steps appended in import order
+- `pre-agent-steps:` - Steps appended in import order
+- `post-steps:` - Steps appended in import order
 - `jobs.<job-id>.setup-steps` and `jobs.<job-id>.pre-steps` - Merged per job with imported steps first, then main workflow steps.
 - Job hook execution order remains: `jobs.<job-id>.setup-steps` runs before `jobs.<job-id>.pre-steps`.
 - `runtimes:`, `network:`, `permissions:`, `services:`, `cache:`, `features:`, `mcp-servers:`

From a9dc14224926b5c187c96f06715d076954936c8a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 6 Jun 2026 23:00:33 +0000
Subject: [PATCH 10/13] docs(aw): finalize setup-steps ordering and placeholder
 text

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/aw/syntax-agentic.md       | 2 +-
 .github/aw/syntax-tools-imports.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/aw/syntax-agentic.md b/.github/aw/syntax-agentic.md
index e5dbf66ce3f..b96d9b48234 100644
--- a/.github/aw/syntax-agentic.md
+++ b/.github/aw/syntax-agentic.md
@@ -276,7 +276,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
             uses: aws-actions/configure-aws-credentials@v4
             with:
               # Replace with your AWS account role ARN.
-              role-to-assume: arn:aws:iam::123456789012:role/gh-aw-activation
+              role-to-assume: arn:aws:iam::YOUR_ACCOUNT_ID:role/gh-aw-activation
               aws-region: us-east-1
           - name: Fetch bootstrap token
             id: bootstrap
diff --git a/.github/aw/syntax-tools-imports.md b/.github/aw/syntax-tools-imports.md
index a9498584afc..25131a7e51c 100644
--- a/.github/aw/syntax-tools-imports.md
+++ b/.github/aw/syntax-tools-imports.md
@@ -273,7 +273,7 @@ The following frontmatter fields in imported files are merged into the importing
 - `pre-agent-steps:` - Steps appended in import order
 - `post-steps:` - Steps appended in import order
 - `jobs.<job-id>.setup-steps` and `jobs.<job-id>.pre-steps` - Merged per job with imported steps first, then main workflow steps.
-- Job hook execution order remains: `jobs.<job-id>.setup-steps` runs before `jobs.<job-id>.pre-steps`.
+- Job hook execution order is: `jobs.<job-id>.setup-steps` runs before `jobs.<job-id>.pre-steps`.
 - `runtimes:`, `network:`, `permissions:`, `services:`, `cache:`, `features:`, `mcp-servers:`
 
 Example import file:

From 0a537f56856ec30ead8d76e27feb5cd9560f891c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 6 Jun 2026 23:01:24 +0000
Subject: [PATCH 11/13] docs(aw): normalize account id placeholder format

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/aw/syntax-agentic.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/aw/syntax-agentic.md b/.github/aw/syntax-agentic.md
index b96d9b48234..8a51c883df2 100644
--- a/.github/aw/syntax-agentic.md
+++ b/.github/aw/syntax-agentic.md
@@ -276,7 +276,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
             uses: aws-actions/configure-aws-credentials@v4
             with:
               # Replace with your AWS account role ARN.
-              role-to-assume: arn:aws:iam::YOUR_ACCOUNT_ID:role/gh-aw-activation
+              role-to-assume: arn:aws:iam::<your-account-id>:role/gh-aw-activation
               aws-region: us-east-1
           - name: Fetch bootstrap token
             id: bootstrap

From f3ba923c3752698cdfc4d7f517bc91be16137855 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 6 Jun 2026 23:02:27 +0000
Subject: [PATCH 12/13] docs(aw): tighten pre-steps timing and import hook
 order text

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/aw/syntax-agentic.md       | 4 ++--
 .github/aw/syntax-tools-imports.md | 3 +--
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/.github/aw/syntax-agentic.md b/.github/aw/syntax-agentic.md
index 8a51c883df2..14d840b4c3a 100644
--- a/.github/aw/syntax-agentic.md
+++ b/.github/aw/syntax-agentic.md
@@ -246,7 +246,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
   - For most agentic workflows, jobs are auto-generated; only specify this for advanced multi-job workflows
   - **Security Notice**: Custom jobs run OUTSIDE the firewall sandbox. Execute with standard GitHub Actions security but NO network egress controls. Use only for deterministic preprocessing, data fetching, or static analysis—not agentic compute or untrusted AI execution.
   - **`setup-steps:`** - Steps injected at the earliest point in a custom or built-in job, before framework GitHub App token minting and before checkout (array). Use this for OIDC login, secret fetch, and credential bootstrap that must happen before framework token/checkout steps. Imported `setup-steps` run before main workflow `setup-steps`.
-  - **`pre-steps:`** - Steps injected after job setup scaffolding and before the job's main `steps:` in a custom or built-in job (array). For built-in jobs (`activation`, `pre_activation`), injected after the `id: setup` step and before the first checkout. Imported `pre-steps` run before main workflow `pre-steps`.
+  - **`pre-steps:`** - Steps injected after framework setup scaffolding and before the job's main `steps:` in a custom or built-in job (array). For built-in jobs, this is after the `id: setup` step (which includes framework token minting/checkout setup) and before the first checkout. Imported `pre-steps` run before main workflow `pre-steps`.
   - **`setup-steps` vs `pre-steps`** - Use `setup-steps` for work that must run before framework GitHub App token minting and checkout (e.g., OIDC/secret bootstrap). Use `pre-steps` for work that should run later, after setup scaffolding and before the job's main `steps:`.
   - **Migration note** - No migration is required. `setup-steps` is additive; existing workflows that only use `pre-steps` continue to behave as before.
   - Example:
@@ -276,7 +276,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
             uses: aws-actions/configure-aws-credentials@v4
             with:
               # Replace with your AWS account role ARN.
-              role-to-assume: arn:aws:iam::<your-account-id>:role/gh-aw-activation
+              role-to-assume: arn:aws:iam::123456789012:role/gh-aw-activation
               aws-region: us-east-1
           - name: Fetch bootstrap token
             id: bootstrap
diff --git a/.github/aw/syntax-tools-imports.md b/.github/aw/syntax-tools-imports.md
index 25131a7e51c..403654f5350 100644
--- a/.github/aw/syntax-tools-imports.md
+++ b/.github/aw/syntax-tools-imports.md
@@ -272,8 +272,7 @@ The following frontmatter fields in imported files are merged into the importing
 - `steps:` - Steps appended in import order
 - `pre-agent-steps:` - Steps appended in import order
 - `post-steps:` - Steps appended in import order
-- `jobs.<job-id>.setup-steps` and `jobs.<job-id>.pre-steps` - Merged per job with imported steps first, then main workflow steps.
-- Job hook execution order is: `jobs.<job-id>.setup-steps` runs before `jobs.<job-id>.pre-steps`.
+- `jobs.<job-id>.setup-steps` and `jobs.<job-id>.pre-steps` - Merged per job with imported steps first, then main workflow steps. Execution order is `setup-steps` before `pre-steps`.
 - `runtimes:`, `network:`, `permissions:`, `services:`, `cache:`, `features:`, `mcp-servers:`
 
 Example import file:

From 089648e5ee3a27ae13bd31ba47b533c43544e371 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 6 Jun 2026 23:03:16 +0000
Subject: [PATCH 13/13] docs(aw): clarify setup-steps account ID placeholder

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/aw/syntax-agentic.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/aw/syntax-agentic.md b/.github/aw/syntax-agentic.md
index 14d840b4c3a..675066b8078 100644
--- a/.github/aw/syntax-agentic.md
+++ b/.github/aw/syntax-agentic.md
@@ -275,7 +275,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
           - name: Configure cloud credentials with OIDC
             uses: aws-actions/configure-aws-credentials@v4
             with:
-              # Replace with your AWS account role ARN.
+              # Replace with your AWS account ID and role ARN.
               role-to-assume: arn:aws:iam::123456789012:role/gh-aw-activation
               aws-region: us-east-1
           - name: Fetch bootstrap token