ADO管道extends模板遍历stage.jobs报Unexpected value job错误

报错现象 #

开发Azure DevOps（ADO）管道安全管控类extends类型YAML模板时，验证或运行流水线返回如下错误：

/ADO_Stage_Restrictions_Dev.yml@AdoRestrictions (Line: 7, Col: 3): Unexpected value job

相关文件内容 #

可正常运行的扩展模板YAML #

该模板可正常通过验证并执行，可确认stages对象已成功传入extends模板

parameters:
  - name: stageObjs
    type: stageList
    default: []

stages:
- ${{ each stage in parameters.stageObjs }}:
    ${{ stage }}

报错的扩展模板YAML #

该模板无法通过验证，抛出上述Unexpected value job异常。按照stage的schema定义，原本预期可以遍历stage内的jobs属性

parameters:
  - name: stageObjs
    type: stageList
    default: []

stages:
- ${{ each stage in parameters.stageObjs }}:
  - ${{ each job in stage.jobs }}:
      ${{ job }}

主流水线入口YAML #

即调用扩展模板的入口Build文件

resources:
  repositories:
    - repository: self
      type: git
      ref: refs/heads/Development
      
    - repository: AdoRestrictions
      type: git
      name: utl-yaml-templates
      ref: refs/heads/main

trigger: none

pool:
    name: PROD    

extends:
  template: ADO_Stage_Restrictions_Dev.yml@AdoRestrictions
  parameters:
    stageObjs:
      - stage: 'BuildStage'
        displayName: 'Build Test'
        jobs:
          - job: 'BuildJob'
            displayName: 'Build'
            steps:
            - task: PowerShell@2
              displayName: 'Hello World'
              inputs:
                targetType: inline
                script: |
                  Write-Host "Hello World"

根因分析 #

• 核心问题是模板写法不符合ADO YAML的层级schema要求：报错模板中内层遍历jobs的- ${{ each job in stage.jobs }}被解析为stages数组的直接子项，而非stage对象的内部属性。模板引擎展开后，会直接在stages层级下生成job节点，但stages数组仅允许接收stage类型的子项，不支持直接放置job，因此抛出值类型不匹配的错误。
• 原写法完全丢失了stage的外层包裹结构，展开后等价于生成了stages: [job1, job2...]的非法结构，而非合法的stages: [{stage: 阶段名, jobs: [job1, job2...]}]结构。

修复方案 #

遍历stage时必须先构造合法的stage对象外壳，保留stage的顶层必填属性，再在stage的jobs字段下遍历job列表，修复后的模板示例如下：

parameters:
  - name: stageObjs
    type: stageList
    default: []

stages:
- ${{ each stage in parameters.stageObjs }}:
  - stage: ${{ stage.stage }}
    displayName: ${{ stage.displayName }}
    # 若stage存在其他顶层属性（如dependsOn、variables、pool、lockBehavior、checkout等），按需在此处按相同格式透传
    jobs:
    - ${{ each job in stage.jobs }}:
        ${{ job }}

如果需要对job做安全管控校验（比如校验job是否绑定了合规pool、是否包含禁止的任务等），可以在jobs的each循环内插入校验逻辑，校验通过后再输出job对象即可。

内容的提问来源于stack exchange，提问作者Bri