Skip to content

docs: fix template marker documentation drift #761

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jamesadevine merged 1 commit into from
May 26, 2026
Merged

docs: fix template marker documentation drift #761

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 44 additions & 17 deletions docs/template-markers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)/<relative-path>.md`
- Additional checkouts present: `$(Build.SourcesDirectory)/$(Build.Repository.Name)/<relative-path>.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)/<relative-path>.md`
- Additional checkouts present: `$(Build.SourcesDirectory)/$(Build.Repository.Name)/<relative-path>.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 }}

Expand Down Expand Up @@ -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`
Expand Down