templateContext Deep Dive: Bundling Metadata with Jobs and Stages

You are building a central template that accepts a list of jobs. But you need each job to carry its own “owner” email and “security_tier” without forcing every developer to use a custom job schema. You try adding these as parameters, but Azure DevOps throws a schema validation error because owner is not a valid property of a job. You are stuck between breaking the standard or losing your metadata.

The templateContext property is one of the most powerful, yet least understood, features in the Azure DevOps YAML engine. It was designed to solve the “Encapsulation Gap”—the inability to attach non-functional metadata to standard pipeline objects (stages, jobs, and steps). Without templateContext, you are often forced to use complex object mapping or global variables, both of which leak logic and make templates harder to maintain. This guide provides a deep dive into templateContext, teaching you how to “smuggle” custom data into your templates and use it to drive sophisticated governance logic.

1. The “Encapsulation Gap” and the Schema Problem

Standard objects like jobList, stageList, and stepList have strict, hard-coded schemas in Azure DevOps. The validator checks for valid properties like pool, steps, or variables. If you attempt to add an arbitrary property—such as appId: 123—directly to a job definition, the orchestrator rejects the YAML with an “Unexpected property” error.

The Encapsulation Gap (The Schema Problem)

This rigidity creates a conflict for Platform Engineering teams. They want to provide developers with the familiarity of the standard job schema (to use IDE autocomplete and validation), but they also need to collect extra metadata to drive automated governance, auditing, and cost tracking.

1.1: Enter templateContext

templateContext is a specialized “safe harbor” object within these standard schemas. The Azure DevOps validator explicitly ignores the contents of the templateContext block, making it the perfect container for any custom data you need. It allows you to keep your metadata tightly coupled with the object it describes, rather than maintaining a separate parallel array that is difficult to keep in sync.

2. Implementing templateContext in Your Templates

To use this feature, your template must define a parameter of a specific list type, such as jobList or stageList.

2.1: The Caller Side (Passing Data)

When a developer calls your template, they include the templateContext property within their job or stage definitions.

# azure-pipelines.yml
- template: governed-jobs.yml
  parameters:
    jobs:
    - job: BuildApp
      templateContext:
        securityTier: 'Critical'
        owner: 'platform-team'
      steps:
      - script: npm run build

2.2: The Receiver Side (Accessing Data)

Inside your template, you iterate through the jobs using an ${{ each }} loop. The metadata is accessible as a property of the loop variable.

The Wrapper Pattern (Using templateContext)

# governed-jobs.yml
parameters:
- name: jobs
  type: jobList

jobs:
- ${{ each job in parameters.jobs }}:
  - job: ${{ job.job }}
    # Accessing the context
    variables:
      tier: ${{ job.templateContext.securityTier }}
    steps:
    - ${{ if eq(job.templateContext.securityTier, 'Critical') }}:
      - task: SecurityAudit@1
    - ${{ job.steps }}

Evaluation Timing: Like all ${{ }} expressions, templateContext is resolved at compile-time. It cannot contain values derived from runtime scripts or task outputs.

3. Scenario: Metadata-Driven Governance

The true value of templateContext lies in building “Opinionated Platforms.”

3.1: Conditional Task Injection

A common use case is the “Policy Wrapper.” A central template accepts a list of jobs from any team in the company. It uses the templateContext.scan property to decide whether to inject a SonarQube task or a DockerPush task. This ensures that the platform enforces the correct security controls without you having to manually add them to every file.

Metadata-Driven Governance Flow

3.2: Dynamic Agent Selection

You can also use metadata to drive infrastructure decisions. For instance, you could route jobs to specific agent pools based on a templateContext.os property. This keeps the job definition clean and allows the platform team to manage the mapping between “OS requirement” and “Agent Pool Name” centrally.

4. templateContext vs. Custom Object Parameters

Use templateContext when you want to extend the standard job/stage experience with “hints.” Use custom objects when your template is an entirely abstract factory that doesn’t map to standard pipeline concepts.

5. Debugging Metadata Failures

If your logic isn’t triggering, the most common culprit is a Type Mismatch. Ensure your parameter is explicitly typed as jobList, deploymentList, stageList, or stepList. If you define the parameter as type: object, the validator may not correctly preserve the templateContext property during expansion.

Use the Expanded YAML view (Run summary -> Download logs) to verify that your metadata properties are actually reaching the inner logic. If ${{ job.templateContext.tier }} returns null in the logs, check for shadowing—ensure that if you are nesting loops, your loop variables (e.g., job_item) are unique.

Hands-On Example: The “Audit-Ready” Pipeline

Here is a template that automatically injects a “Log-to-Compliance” step for every job, using a ComplianceID passed via context.

# templates/governed-jobs.yml
parameters:
- name: jobs
  type: jobList

jobs:
- ${{ each job in parameters.jobs }}:
  - ${{ each pair in job }}:
      ${{ if ne(pair.key, 'steps') }}:
        ${{ pair.key }}: ${{ pair.value }}
    steps:
    - script: echo "Audit Log for ID: ${{ job.templateContext.ComplianceID }}"
    - ${{ job.steps }}

This ensures every job has a mandatory audit trail, but you only see your standard job logic in your own repository.

Key Takeaways

1. Keep Data Local: Use templateContext to keep metadata attached to the specific jobs it describes.
2. Standardize Your Context Schema: Define an internal standard (e.g., every job must have an owner) to keep your platform predictable.
3. Fail Gracefully: Use ${{ coalesce() }} to provide defaults if the templateContext is missing.
4. Don’t Pass Secrets: Metadata is visible in expanded logs. Pass secret names, never values.

Sources

• Microsoft Learn: templateContext property reference
• Microsoft Learn: jobList parameter type
• Azure DevOps Community: Advanced Metadata Patterns
• GitHub: Enterprise-Scale YAML Library Examples