From b79a200d1bea729419b88d090a7bdc16d7fa33e7 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 29 May 2026 21:30:31 +0000 Subject: [PATCH] docs(site): document custom steps injection in front-matter reference Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../content/docs/reference/front-matter.mdx | 159 +++++++++++++++++- 1 file changed, 157 insertions(+), 2 deletions(-) diff --git a/site/src/content/docs/reference/front-matter.mdx b/site/src/content/docs/reference/front-matter.mdx index 98236c90..5a7ec6b7 100644 --- a/site/src/content/docs/reference/front-matter.mdx +++ b/site/src/content/docs/reference/front-matter.mdx @@ -59,8 +59,8 @@ runtimes: # optional runtime configuration (language enviro # dotnet: # Alternative object format (pin version, configure internal feed via nuget.config) # version: "8.0.x" # use "global.json" to pin from the repo's global.json # feed-url: "https://pkgs.dev.azure.com/myorg/_packaging/myfeed/nuget/v3/index.json" -# env: # RESERVED: workflow-level environment variables (not yet implemented) -# CUSTOM_VAR: "value" +# env: # RESERVED: workflow-level environment variables (field exists but not yet used by compiler) +# CUSTOM_VAR: "value" # For now, use engine.env or mcp-servers..env for process-specific vars # inlined-imports: false # When true, resolve {{#runtime-import ...}} markers at compile time # # (default: false -- markers are resolved at pipeline runtime, so # # prompt-body edits do not require recompilation). @@ -240,6 +240,161 @@ becomes a `repos:` entry, with `checkout: false` added for entries that weren't listed under `checkout:`. Mixing the legacy fields with an existing `repos:` block is rejected; pick one shape. +## Custom Steps Injection + +The `steps`, `post-steps`, `setup`, and `teardown` fields let you inject custom ADO pipeline steps at specific points in the compiled workflow's execution flow. + +### Execution Order + +Custom steps are inserted at these points in the three-stage pipeline: + +```mermaid +flowchart TB + subgraph SetupJob[Setup Job] + S1[setup steps] + S2[Gate step] + S3[Runtime setup] + end + subgraph AgentJob[Agent Job] + A1[steps] + A2[Run agent] + A3[post-steps] + end + subgraph ExecutorJob[Executor Job] + E1[Execute safe outputs] + end + subgraph TeardownJob[Teardown Job] + T1[teardown steps] + end + S1 --> S2 --> S3 --> A1 --> A2 --> A3 --> E1 --> T1 +``` + +| Field | Job | Position | Use Cases | +|-------|-----|----------|-----------| +| `setup` | Setup (separate job) | **Before** gate step and runtime setup | Pre-flight checks, credentials setup, external service initialization | +| `steps` | Agent (inline) | **Before** agent runs | Generate context files, fetch external data, prepare workspace | +| `post-steps` | Agent (inline) | **After** agent completes | Process agent outputs, run validation, upload diagnostics | +| `teardown` | Teardown (separate job) | **After** safe outputs execute | Cleanup, notification, metrics collection | + +### Field Types + +All four fields accept ADO step arrays (YAML sequences). Each step can be any standard ADO task or script: + +```yaml +steps: + - bash: echo "Inline bash step" + displayName: "Prepare context" + - task: DownloadSecureFile@1 + inputs: + secureFile: "config.json" + displayName: "Fetch config" +``` + +### `steps:` — Pre-Agent Context Preparation + +Runs **before** the agent in the same job. Use for generating context the agent needs: + +```yaml +steps: + - bash: | + git log --oneline -10 > /tmp/recent-commits.txt + echo "Recent commits prepared for agent review" + displayName: "Generate commit history" +``` + +The agent can then read `/tmp/recent-commits.txt` when forming its response. + +### `post-steps:` — Post-Agent Processing + +Runs **after** the agent in the same job. Use for processing agent outputs or running validation: + +```yaml +post-steps: + - bash: | + if [ -f agent-output.json ]; then + jq . agent-output.json || echo "Invalid JSON produced by agent" + fi + displayName: "Validate agent output" +``` + +### `setup:` — Pre-Flight Setup Job + +Runs as a **separate job** before the Setup job's gate step. Use for infrastructure provisioning or external service preparation: + +```yaml +setup: + - bash: | + curl -X POST https://api.service.com/start-session \ + -H "Authorization: Bearer $TOKEN" + displayName: "Initialize external service" + env: + TOKEN: $(ExternalServiceToken) +``` + +The Setup job (with `setup:` steps) always runs first, followed by Agent, then Executor, then Teardown. + +### `teardown:` — Post-Execution Cleanup Job + +Runs as a **separate job** after safe outputs execute. Use for cleanup, notifications, or metrics: + +```yaml +teardown: + - bash: | + echo "Pipeline completed. Cleaning up resources." + rm -rf /tmp/agent-workspace + displayName: "Cleanup workspace" +``` + +Teardown steps run even if the agent or executor jobs fail (condition: `always()`). + +### Job Conditions + +- **`setup`** and inline **`steps`** run unconditionally (subject to gate filters) +- **`post-steps`** run only if the agent job reaches that phase (condition: `always()` within the job) +- **`teardown`** runs unconditionally after the executor job completes (condition: `always()`) + +### Example: Full Custom Steps Workflow + +```yaml +--- +name: "data-pipeline" +description: "Fetch, process, and report on external data" +on: + schedule: daily around 06:00 +pool: + vmImage: ubuntu-22.04 +setup: + - bash: | + curl -o /tmp/dataset.csv https://data.example.com/daily.csv + echo "Dataset downloaded and ready" + displayName: "Fetch external dataset" +steps: + - bash: | + wc -l /tmp/dataset.csv > /tmp/row-count.txt + echo "Row count prepared for agent" + displayName: "Generate dataset stats" +post-steps: + - bash: | + echo "Agent completed. Archiving results." + tar -czf agent-results.tar.gz /tmp/agent-*.log + displayName: "Archive logs" + - task: PublishBuildArtifacts@1 + inputs: + pathToPublish: "agent-results.tar.gz" + artifactName: "results" +teardown: + - bash: | + curl -X POST https://webhooks.example.com/notify \ + -d '{"status":"complete","pipeline":"$(Build.DefinitionName)"}' + displayName: "Send completion webhook" +--- + +## Data Pipeline Agent + +Review the dataset statistics in `/tmp/row-count.txt`, process the data in +`/tmp/dataset.csv`, and summarize any anomalies or trends. +``` + ## Inlined Imports The `inlined-imports:` field controls when `{{#runtime-import ...}}`