diff --git a/docs/parameters.md b/docs/parameters.md index 49d86b769..a72d1aac9 100644 --- a/docs/parameters.md +++ b/docs/parameters.md @@ -43,3 +43,12 @@ When `tools.cache-memory` is configured, the compiler automatically injects a `c - Creates an empty memory directory so the agent starts fresh If you define your own `clearMemory` parameter in the front matter, the auto-injected one is suppressed — your definition takes precedence. + +### Reserved names on `target: job` / `target: stage` + +On these two targets the compiler auto-injects its own `dependsOn` and +`condition` template parameters (see [`docs/targets.md`](targets.md)) so +callers can wire in external ordering at the `template:` invocation site. +Declaring a front-matter `parameters:` entry named `dependsOn` or `condition` +on `target: job` or `target: stage` is therefore a **compile-time error** — +rename the parameter or switch targets. diff --git a/docs/targets.md b/docs/targets.md index 2af8c7169..e65995d63 100644 --- a/docs/targets.md +++ b/docs/targets.md @@ -97,6 +97,9 @@ stages: - The `condition` parameter is ANDed into the agent job's existing internal condition (PR gate, pipeline gate, etc.). Empty default preserves ADO's native `succeeded()` behaviour. +- `dependsOn` and `condition` are reserved parameter names on `target: job`. + Declaring a front-matter `parameters:` entry with either name is a + **compile-time error** — rename the parameter or drop `target: job`. - Triggers (`on:`) are ignored with a warning (the parent pipeline controls triggers). - If the agent declares additional repositories via `repos:`, add them to the parent pipeline's `resources:` block (documented in the generated file header). @@ -136,6 +139,9 @@ stages: behaviour. - The `dependsOn` parameter is typed `object`, matching ADO's native `dependsOn:` semantics (accepts a single string or a list). +- `dependsOn` and `condition` are reserved parameter names on `target: stage`, + same as `target: job` — a front-matter `parameters:` entry with either name + is a **compile-time error**. - Same 3-job chain, job-name prefixing, and pool handling as `target: job`. - Triggers (`on:`) are ignored with a warning. - If the agent declares additional repositories via `repos:`, add them to the