Enforcing Pipeline Governance with Azure DevOps YAML 'extends' Templates and Required Template Checks

Desired outcome

Ensure every pipeline that deploys to a protected environment follows a common structure defined in a central YAML template, preventing ad‑hoc stages or steps.

Prerequisites

• Permission to edit pipeline YAML in the project (Contributor or higher).
• Administrator rights on the environment or service connection that will be protected.
• Access to the Git repository that will hold the root template (can be the same repo or a separate one).

Step 1 – Author the root template

Create a YAML file that defines the full stage/job skeleton and exposes parameters for the parts that must vary per pipeline.

# templates/pipeline-root.yml
parameters:
- name: environment
  type: string
  default: 'dev'
- name: extraSteps
  type: object
  default: []

stages:
- stage: Build
  displayName: Build application
  jobs:
  - job: build
    pool: vmImage: 'ubuntu-latest'
    steps:
    - script: echo "Building ${{ parameters.environment }}"
      displayName: 'Print build message'

- stage: Deploy
  displayName: Deploy to ${{ parameters.environment }}
  dependsOn: Build
  condition: succeeded()
  jobs:
  - deployment: deploy
    environment: ${{ parameters.environment }}
    strategy:
      runOnce:
        deploy:
          steps:
          - script: echo "Deploying to ${{ parameters.environment }}"
            displayName: 'Print deploy message'
          - ${{ each step in parameters.extraSteps }}:
            - ${{ step }}

This template controls the stages, jobs, and steps; child pipelines can only supply values for the parameters.

Step 2 – Commit the template

Commit pipeline-root.yml to a branch (e.g., main) in the template repository and note the full path and repo name.

Step 3 – Reference the template from a child pipeline

In each project that needs to deploy, create a pipeline YAML that uses the extends keyword.

extends:
  template: pipeline-root.yml@Templates  # Templates is the repository resource name
parameters:
  environment: 'prod'
  extraSteps:
    - script: echo "Running extra validation"
      displayName: 'Extra validation'

Save and run the pipeline; the Azure Pipelines engine expands the template at compile time.

Step 4 – Add a Required template check

Navigate to the protected environment (or service connection) → Approvals and checks → New check → Required template. Fill in:

• Template repository: the same repo used in Step 2.
• Template path: templates/pipeline-root.yml (or the path you committed).
• Optional: specify a branch or tag to lock the template version.

Save the check. Any pipeline that attempts to use this environment without extending the approved template will be blocked at the resource check stage.

Expected checks

• Non‑compliant run: The pipeline starts, reaches the Approvals and checks stage for the environment, fails the Required template check, and never proceeds to any job. The UI shows a red “Check failed” badge.
• Compliant run: The check passes, the pipeline proceeds, and the expanded steps from the template appear in the logs (you can see the echo statements from the root template).

Use the pipeline editor’s Validate button or a dry‑run to confirm that template expressions expand correctly before queuing a run.

Recovery options

If the check blocks a legitimate pipeline:

1. Temporarily disable or delete the Required template check on the environment to unblock deployments while you investigate.
2. Keep a previous version of the template on a branch or tag (e.g., v1.0) so consumers can pin to it by changing the repository resource reference.
3. Validate template changes in a non‑production environment first; use a separate environment without the check to test new parameters or steps.

Limitations and verification

Required template checks only gate pipelines that consume the protected resource; pipelines that do not use that environment or service connection can still bypass the template. Exact UI placement and supported features may evolve; consult the current Azure Pipelines documentation for “extends templates” and “required template check” to confirm availability in your tenancy. Before applying the check in production, create a sandbox project, add an environment with the check, and verify that a non‑extending pipeline is rejected while an extending one passes.