Skip to content

docs(site): fix job/stage targets — dependsOn and condition must be parameters #830

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
Jun 2, 2026
Merged

docs(site): fix job/stage targets — dependsOn and condition must be parameters #830

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
35 changes: 26 additions & 9 deletions site/src/content/docs/reference/targets.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ The `target` field in the front matter determines the output format and executio
### `standalone` (default)

Generates a self-contained Azure DevOps pipeline with:
- Full 3-job pipeline: `Agent` -> `Detection` -> `SafeOutputs`
- Full 3-job pipeline: `Agent` → `Detection` → `SafeOutputs`
- AWF (Agentic Workflow Firewall) L7 domain whitelisting via Squid proxy + Docker
- MCP Gateway (MCPG) for MCP routing with SafeOutputs HTTP backend
- Setup/teardown job support
Expand All @@ -25,7 +25,7 @@ This is the recommended target for maximum flexibility and security controls.
Generates a pipeline that extends the 1ES Unofficial Pipeline Template:
- Uses `templateContext.type: buildJob` with Copilot CLI + AWF + MCPG (same execution model as standalone)
- Integrates with 1ES SDL scanning and compliance tools
- Full 3-job pipeline: Agent -> Detection -> SafeOutputs
- Full 3-job pipeline: Agent → Detection → SafeOutputs
- Requires 1ES Pipeline Templates repository access

Example:
Expand All @@ -38,14 +38,14 @@ When using `target: 1es`, the pipeline will extend `1es/1ES.Unofficial.PipelineT
### `job`

Generates a **job-level ADO YAML template** with `jobs:` at root. This is a
reusable template that can be included in an existing pipeline -- it does not
reusable template that can be included in an existing pipeline — it does not
generate a complete pipeline.

The output contains the same 3-job chain (Agent -> Detection -> SafeOutputs) as
The output contains the same 3-job chain (Agent → Detection → SafeOutputs) as
`standalone`, with:
- Job names prefixed with the agent name for uniqueness (e.g., `DailyReview_Agent`)
- No triggers, pipeline name, or resource declarations (the parent pipeline owns those)
- Pool baked in from the front matter `pool:` field
- Pool baked in from the front matter `pool:` field (`vmImage` or `name`; defaults to `vmImage: ubuntu-22.04`)

Example front matter:
```yaml
Expand All @@ -59,6 +59,9 @@ jobs:
- job: Build
steps: ...
- template: agents/review.lock.yml
parameters:
dependsOn: [Build] # list of upstream job names; omit for implicit dep on previous job
condition: succeeded('Build') # optional; ANDed into the agent job's internal condition
```

#### Usage inside a user-defined stage
Expand All @@ -73,6 +76,12 @@ stages:
- template: agents/review.lock.yml
```

#### Notes

- ADO's [`jobs.template`](https://learn.microsoft.com/azure/devops/pipelines/yaml-schema/jobs-template) schema only allows `template:` and `parameters:` at the call site. `dependsOn:` and `condition:` as bare keys on the `- template:` line are rejected; the compiled template surfaces them as parameters and applies them to the agent job internally.
- When the agent has a Setup job (e.g. PR or pipeline filters), the `dependsOn` parameter **must** be a YAML list — the template uses `${{ each }}` to merge `Setup` with the caller's deps, and `${{ each }}` requires an iterable. For agents without a Setup job, either a string or a list works.
- The `condition` parameter is ANDed into the agent job's existing internal condition. Omit it to preserve ADO's native `succeeded()` behaviour.

### `stage`

Generates a **stage-level ADO YAML template** with `stages:` at root. This
Expand All @@ -91,12 +100,16 @@ stages:
- stage: Build
jobs: ...
- template: agents/review.lock.yml
dependsOn: Build
condition: succeeded()
parameters:
dependsOn: Build # or [Build, Test]; omit for implicit dep on previous stage
condition: succeeded('Build') # optional; omit for ADO's default succeeded()
```

ADO natively supports `dependsOn` and `condition` at the template call site --
no template parameters are needed for stage ordering.
#### Notes

- ADO's [`stages.template`](https://learn.microsoft.com/azure/devops/pipelines/yaml-schema/stages-template) schema only allows `template:` and `parameters:` at the call site. `dependsOn:` and `condition:` as bare top-level keys on the `- template:` line are **rejected** by the YAML parser. The compiled template surfaces them as parameters and applies them to the inner stage block.
- The `dependsOn` parameter accepts a single string or a list (matching ADO's native `dependsOn:` semantics).
- Same 3-job chain, job-name prefixing, and pool handling as `target: job`.

---

Expand All @@ -109,3 +122,7 @@ If your agent declares additional repositories via `repos:`, you must manually a
</Aside>

Both `job` and `stage` targets produce templates with the same 3-job execution chain (Agent → Detection → SafeOutputs), job-name prefixing for uniqueness, and pool configuration baked in from the `pool:` front-matter field. The difference is only in the YAML wrapper: `jobs:` at root vs. `stages:` at root.

<Aside type="caution" title="dependsOn and condition must be parameters">
ADO's template call-site schema only allows `template:` and `parameters:` as top-level keys on a `- template:` entry. Bare `dependsOn:` and `condition:` keys on the `- template:` line are rejected by ADO. Always pass them through `parameters:` as shown in the usage examples above.
</Aside>