Azure DevOps Pipelines Template

Purpose

Build production-grade Azure Pipelines template systems for Azure Repos. Reuse one CI core across PR and main, keep templates self-contained, and make variable timing explicit so behavior is predictable.

Non-Negotiable Rules

• •Target Azure DevOps Repos and Azure Pipelines YAML only.
• •Never rely on YAML pr: for Azure Repos PR validation.
• •Always treat templates as APIs: declare all required inputs explicitly.
• •Never assume caller-defined variables exist unless passed or declared.
• •Prefer typed parameters over implicit string variables for control flow.

Pairing Contract with azuredevops-pipelines-logging

Use both skills when template design and script signaling intersect:

• •This skill owns template topology, trigger strategy, parameter contracts, compile-time shape, and runtime conditions.
• •azuredevops-pipelines-logging owns ##vso[...] and ##[...] command correctness, escaping, masking, and output-variable propagation details.
• •Keep responsibilities explicit: this skill chooses the variable flow model; logging skill defines the exact command lines that implement it.

Standard Topology

Use three files as a baseline:

1. •azure-pipelines-pr.yml - branch-policy validation pipeline for PRs.
2. •azure-pipelines-main.yml - post-merge main CI pipeline.
3. •templates/ci-core.yml - shared implementation logic.

The two entry pipelines should only set triggers and template parameters. Keep all jobs, stages, and steps in the shared template.

PR vs Main Pattern (Azure Repos)

• •azure-pipelines-pr.yml should use trigger: none and pr: none; connect this pipeline to target branches via Build Validation branch policy.
• •azure-pipelines-main.yml should use CI trigger on main and pr: none.
• •Reuse the same core template with different parameters:
  • •PR: fast checks, no heavy integration suite.
  • •Main: same core checks plus heavy integration jobs or stages.

Variable and Expression Contract

Choose syntax by evaluation phase:

• •${{ }} compile-time template expression:
  • •Use for template structure (if, each, template insertion).
  • •Has access to parameters and static variables only.
• •$[ ] runtime expression:
  • •Use for runtime conditions and computed variable values.
  • •Does not access template parameters.
• •$( ) macro syntax:
  • •Use inside task inputs and scripts.
  • •Expands before each task.

Never mix these syntaxes casually. Most template bugs are timing bugs.

Self-Contained Template API Pattern

For each template:

1. •Declare all parameters with type and sensible defaults.
2. •Constrain string parameters using values: when practical.
3. •Define template-owned variables locally in the template.
4. •Pass caller data via parameters, not hidden globals.
5. •Use typed extension points (stepList, jobList, stageList) where needed.

Typed Extension Points

• •Use stepList to inject controlled step hooks.
• •Use jobList with templateContext for suite metadata and fan-out jobs.
• •Use stageList for environment promotion templates.
• •In templates, use object instead of stringList.

Dependency Management (TypeScript, Python, R)

Design dependency installation as dedicated step templates and include them from ci-core.yml based on typed parameters.

• •TypeScript: bun install --frozen-lockfile or npm ci.
• •Python: pixi install, pixi run <task>.
• •R: pixi install, pixi run <task>.

Use one explicit parameter (for example dependencyMode: fast|locked) to alter install strictness between PR and main.

Workflow

1. •Pick topology (pr/main/core) and draft template API.
2. •Define a parameter table (name, type, default, allowed values).
3. •Implement compile-time structure with ${{ }} only.
4. •Add runtime condition: logic with $[ ] where required.
5. •Delegate script-level signaling and ##vso[...] command details to azuredevops-pipelines-logging when needed.
6. •Wire TS/Python/R dependency templates via explicit parameters.
7. •Validate PR and main paths execute expected job sets.

Output Contract

When this skill is used, return:

1. •Concrete pipeline topology (pr/main/core) and file map.
2. •Copy-paste YAML snippets for entry pipelines and shared template sections.
3. •Variable and expression timing rationale for each decision.
4. •Parameter contract table and validation checklist.
5. •Azure Repos branch-policy guidance for PR validation.

Companion Skill

• •azuredevops-pipelines-logging: load when the template design requires concrete ##vso[...] command snippets, output variable propagation, secret masking, or rich log formatting semantics.

References (Load on Demand)

• •references/azure-repos-pr-validation.md
  • •Load when implementing PR validation behavior in Azure Repos.
• •references/template-architecture.md
  • •Load when implementing shared core templates for PR/main reuse.
• •references/variables-and-expressions.md
  • •Load when debugging compile-time versus runtime behavior.
• •references/typed-parameters.md
  • •Load when designing stepList, jobList, and stageList APIs.
• •references/dependency-management-ts-python-r.md
  • •Load when implementing bun/npm/pixi dependency install patterns.
• •references/azure-devops-mcp-opencode.md
  • •Load when configuring Azure DevOps MCP in OpenCode.
• •references/sources-and-slugs.md
  • •Load when source traceability is required.