From 30605eeeee644d8198e40de90288774cfcef5ce5 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 26 May 2026 17:41:33 +0000 Subject: [PATCH] docs: fix template marker documentation drift - Add documentation for {{ stage_prefix }} marker used in job-base.yml and stage-base.yml - Add documentation for {{ template_parameters }} marker used in job-base.yml and stage-base.yml - Remove obsolete {{ pipeline_path }} and {{ trigger_repo_directory }} marker documentation (no longer used in any template) - Mark {{ mcp_client_config }} as obsolete in the heading These markers are actively used in the job and stage templates but were not documented, while the obsolete markers were still documented as if they were current. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/template-markers.md | 61 +++++++++++++++++++++++++++++----------- 1 file changed, 44 insertions(+), 17 deletions(-) diff --git a/docs/template-markers.md b/docs/template-markers.md index 0acf8a9a..cf0246e2 100644 --- a/docs/template-markers.md +++ b/docs/template-markers.md @@ -320,31 +320,58 @@ workspace: exp23-a7-nw # Resolves to $(Build.SourcesDirectory)/exp23-a7-nw This is used for the `workingDirectory` property of the copilot task. -> **Alias:** `{{ workspace }}` is registered as a backward-compatible alias for `{{ working_directory }}` and expands to the same value. Prefer `{{ working_directory }}` in new templates. For paths that must always resolve to the trigger repo (not the agent workspace), use [`{{ trigger_repo_directory }}`](#-trigger_repo_directory-) instead. +> **Alias:** `{{ workspace }}` is registered as a backward-compatible alias for `{{ working_directory }}` and expands to the same value. Prefer `{{ working_directory }}` in new templates. -## {{ source_path }} +## {{ stage_prefix }} -Should be replaced with the path to the agent markdown source file for Stage 3 execution. The path is anchored at the **trigger ("self") repository** via `{{ trigger_repo_directory }}` (see below), independent of the user's `workspace:` setting, and mirrors the relative path used at compile time: -- No additional checkouts: `$(Build.SourcesDirectory)/.md` -- Additional checkouts present: `$(Build.SourcesDirectory)/$(Build.Repository.Name)/.md` +Should be replaced with a sanitized, PascalCase identifier derived from the agent name for use as a job/stage name prefix in job- and stage-level templates. Generated by `generate_stage_prefix()` in `src/compile/common.rs`. -For example, compiling `agents/my-agent.md` produces a runtime path of `$(Build.SourcesDirectory)/agents/my-agent.md` (or the equivalent under `$(Build.Repository.Name)` when additional repositories are checked out). +The transformation: +1. Strips non-ASCII characters +2. Converts to PascalCase (capitalizes first letter of each word, removes spaces/hyphens/underscores) +3. Prepends `_` if the result starts with a digit +4. Falls back to `"Agent"` if the sanitized result is empty -Used by the execute command's --source parameter. The agent markdown only ever lives in the trigger repo, so this is intentionally not affected by `workspace:` pointing at a non-self alias. +Examples: +- `"Daily Code Review"` → `"DailyCodeReview"` +- `"my-agent-123"` → `"MyAgent123"` +- `"123start"` → `"_123start"` +- `"code_review_agent"` → `"CodeReviewAgent"` -## {{ pipeline_path }} +Used in `src/data/job-base.yml` and `src/data/stage-base.yml` to generate unique job names (`{{ stage_prefix }}_Agent`, `{{ stage_prefix }}_Detection`, `{{ stage_prefix }}_SafeOutputs`) and stage names (`- stage: {{ stage_prefix }}`). This ensures that multiple agents can be included in the same pipeline without job/stage name collisions. -Should be replaced with the path to the compiled pipeline YAML file for runtime integrity checking. The path is **relative** to the trigger repository root (e.g. `agents/ctf.yml`, `pipelines/production/review.lock.yml`). The integrity check step itself sets `workingDirectory: {{ trigger_repo_directory }}` so the relative path resolves correctly regardless of whether additional repositories are checked out, and so that `ado-aw check`'s recompile step has access to the trigger repo's `.git` directory (required to infer the ADO org for `tools.azure-devops`). +## {{ template_parameters }} -Used by the pipeline's integrity check step to verify the pipeline hasn't been modified outside the compilation process. +Should be replaced with the top-level `parameters:` block for job- and stage-level templates. Generated by `generate_template_parameters()` in `src/compile/common.rs`. -## {{ trigger_repo_directory }} +The generated block includes all user-defined parameters from the `parameters:` front matter field, plus any auto-injected parameters (e.g., `clearMemory` when `tools.cache-memory` is configured). -Should be replaced with the directory where the trigger ("self") repository is checked out. This is independent of the `workspace:` setting and depends only on whether any additional repositories are configured with `checkout: true` (the default) in `repos:`: -- No additional checkouts → `$(Build.SourcesDirectory)` (ADO checks `self` into the root) -- One or more additional checkouts → `$(Build.SourcesDirectory)/$(Build.Repository.Name)` (ADO puts each checked-out repo, including `self`, into a subfolder named after the repository) +When no parameters are defined and no auto-injected parameters apply, this marker is replaced with an empty string. -Use this marker (rather than `{{ working_directory }}` / `{{ workspace }}`) for any path that refers to a file shipped in the trigger repo (e.g. the agent markdown source) or as a `workingDirectory:` for steps that need access to the trigger repo's `.git` (e.g. the integrity check step). +Example output: +```yaml +parameters: +- name: clearMemory + displayName: Clear agent memory + type: boolean + default: false +- name: verbose + displayName: Verbose output + type: boolean + default: false +``` + +Used by `src/data/job-base.yml` and `src/data/stage-base.yml` to emit the parameters block at the template root, allowing consumer pipelines to pass runtime parameters through ADO's `templateParameters` mechanism. + +## {{ source_path }} + +Should be replaced with the path to the agent markdown source file for Stage 3 execution. The path is anchored at the **trigger ("self") repository** via `{{ trigger_repo_directory }}` (see below), independent of the user's `workspace:` setting, and mirrors the relative path used at compile time: +- No additional checkouts: `$(Build.SourcesDirectory)/.md` +- Additional checkouts present: `$(Build.SourcesDirectory)/$(Build.Repository.Name)/.md` + +For example, compiling `agents/my-agent.md` produces a runtime path of `$(Build.SourcesDirectory)/agents/my-agent.md` (or the equivalent under `$(Build.Repository.Name)` when additional repositories are checked out). + +Used by the execute command's --source parameter. The agent markdown only ever lives in the trigger repo, so this is intentionally not affected by `workspace:` pointing at a non-self alias. ## {{ integrity_check }} @@ -428,9 +455,9 @@ Generates an `env:` block for the "Start MCP Gateway (MCPG)" pipeline step, forw When no extensions require pipeline variables, this marker is replaced with an empty string and the MCPG step has no `env:` block. -## {{ mcp_client_config }} +## {{ mcp_client_config }} *(obsolete)* -**Removed.** The Copilot CLI `mcp-config.json` is no longer generated at compile time. Instead, it is derived at **pipeline runtime** from MCPG's actual gateway output, matching gh-aw's `convert_gateway_config_copilot.cjs` pattern. +**Removed in recent versions.** The Copilot CLI `mcp-config.json` is no longer generated at compile time. Instead, it is derived at **pipeline runtime** from MCPG's actual gateway output, matching gh-aw's `convert_gateway_config_copilot.cjs` pattern. The "Start MCP Gateway (MCPG)" pipeline step: 1. Redirects MCPG's stdout to `gateway-output.json`