YAML 管道中的资源

Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022 |Azure DevOps Server 2020

本文讨论 YAML 管道的资源。 资源是管道使用的任何内容，该管道存在于该管道外部。 YAML 管道中的资源可以是其他管道、生成、容器、包、存储库或 Webhook。

定义资源时，可以在管道中的任意位置使用资源。 有关详细信息和示例，请参阅 资源定义。

resources:
  pipelines:
  - pipeline: resources1
    source: otherPipeline

steps:
- download: resources1
  artifact: artifact1.txt

可以使用资源状态通过设置资源定义中的属性来自动trigger管道。 然后，管道 resources.triggeringAlias 和 resources.triggeringCategory 变量将设置为资源名称和类别。 除非变量设置为Build.Reason空，否则这些ResourceTrigger变量为空。

资源允许管道使用的服务的完全 可跟踪性 ，包括版本、项目、关联的提交和工作项。 如果订阅了对资源触发事件，则可以完全自动化 DevOps 工作流。

资源授权

资源必须经过授权才能在管道中使用。 资源所有者控制可以访问其资源的用户和管道。 有几种方法可以授权 YAML 管道使用资源。

• 使用资源的管理设置 向所有管道授予访问权限。 例如，可以在 “管道>库 ”页上管理安全文件和变量组，以及 项目设置>管道中的代理池和服务连接。 此授权对于不需要限制的资源（例如测试资源）很方便。

• 请确保在项目的代理池安全角色中至少具有“用户”角色。 创建的 YAML 管道会自动获得 使用用户角色 的资源的授权。

• 如果将资源定义添加到 YAML 管道，但生成失败并出现类似 Could not find a <resource> with name <resource-name>. The <resource> does not exist or has not been authorized for use错误，请确保对资源具有至少 用户 角色。 然后，可以选择对失败的生成中的资源进行授权的选项。 资源获得授权后，可以启动新的生成。

资源的审批检查

可以使用审批检查和模板手动控制资源使用。 通过使用 所需的模板审批检查，可以要求使用特定资源或环境的任何管道从特定的 YAML 模板进行扩展。

设置 所需的模板 审批可以增强安全性，方法是确保仅在特定条件下使用资源。 有关详细信息，请参阅 使用模板实现安全性。

手动资源版本选取器

Azure Pipelines 根据其资源定义评估资源的默认版本。 对于计划运行，如果未手动选择运行，Azure Pipelines 将仅考虑成功完成持续集成（CI）运行以评估默认资源版本。

手动触发 YAML 持续部署（CD）管道时，可以使用手动资源版本选取器来选择不同的资源版本。 管道、生成、存储库、容器和包资源支持资源版本选取器。

对于 pipeline 资源，手动版本选取器允许你查看所有分支中可用的运行，根据管道号或分支搜索运行，并选择成功、失败或正在进行的运行。

在运行 CD 管道之前，无需等待 CI 运行完成或因不相关的故障重新运行。 你可以灵活地选择你知道生成所需的项目的任何运行。

若要使用资源版本选取器，请在“运行管道”窗格中选择“资源”，选择资源，并从可用版本列表中选择特定版本。 对于无法提取可用版本（如 GitHub 包）的资源，可以在文本字段中输入所需的版本。

资源定义

YAML 管道资源可以是：

• 其他管道
• 构建
• 容器
• 包
• 存储库或
• Webhook。

以下部分提供 YAML 管道资源类别的定义和示例。 有关完整的架构信息，请参阅 Azure Pipelines 的 YAML 架构参考中的资源定义。

管道资源

可以将 CI pipeline 资源用作 CD 工作流 的触发器 。 还可以从管道引用pipeline资源来下载项目或使用管道资源变量。 只有 Azure Pipelines 可以使用 pipelines 资源。

在 pipelines 资源定义中：

• pipeline 是用于引用管道资源的唯一名称。
• source 是生成管道项目的管道的名称。

有关完整的架构信息，请参阅 resources.pipelines.pipeline 定义。

管道资源定义示例

以下示例资源定义使用同一 Azure DevOps 项目中管道中的项目。

resources:
  pipelines:
  - pipeline: SmartHotel-resource # identifier to use in pipeline resource variables
    source: SmartHotel-CI # name of the pipeline that produces the artifacts

若要从另一个项目指定管道，请在 project 资源定义中包含名称。 以下示例还用于 branch 在手动或按计划触发管道时解析默认版本。 分支输入不能有通配符。

resources:
  pipelines:
  - pipeline: SmartHotel
    project: otherDevOpsProject
    source: SmartHotel-CI
    branch: releases/M142

资源版本评估

Azure Pipelines 根据其资源定义评估资源的默认版本。 管道的默认资源项目版本取决于管道是手动运行还是按计划运行 ，还是根据 资源运行的结果触发。

对于手动或计划的管道运行，资源定义中的version值branchtags和pipeline属性定义项目版本。 输入 branch 不能有通配符，并且 tags 属性使用 AND 运算符。

对于计划运行，如果未使用版本选取器，Azure Pipelines 将仅考虑评估默认资源版本时成功完成的持续集成（CI）运行。 对于手动运行，可以使用 手动版本选取器替代定义的版本。

下表列出了 pipeline 资源定义属性及其指定的项目版本。

以下 pipeline 资源定义使用 branch 和 tags 属性在手动计划或触发管道时评估默认版本。 项目myCIAlias版本是具有标记main的Production分支上运行PreProduction的最新生成版本。

resources:
  pipelines:
  - pipeline: myCIAlias
    project: Fabrikam
    source: Fabrikam-CI
    branch: main
    tags:
    - Production
    - PreProduction

管道资源触发器

对于针对资源运行结果触发的管道运行， trigger 资源定义中的属性设置确定默认资源项目版本。 若要使用 pipeline 资源作为触发器来运行当前管道，必须设置该 trigger 属性。 如果未包含 trigger 属性，资源运行不会触发当前管道运行。

当管道基于trigger资源定义中的pipeline值触发时，将忽略总体资源定义versionbranch的值和tags属性。 属性 trigger 确定项目版本。

下表介绍了属性如何影响 trigger 触发器行为。

下面的示例演示了一个包含简单 trigger管道资源定义的管道。

resources:
  pipelines:
  - pipeline: SmartHotel
    project: otherDevOpsProject
    source: SmartHotel-CI
    trigger: true

以下示例显示了具有分支条件的管道资源 trigger。

resources:
  pipelines:
  - pipeline: SmartHotel
    project: otherDevOpsProject
    source: SmartHotel-CI
    trigger:
      branches:
      - releases/*
      - resources.triggeringAlias

以下示例使用 stages 筛选器来评估 CD 管道的触发器条件。 触发器 stages 使用 AND 运算符。 CD 管道在成功完成所有列出的阶段后触发。

resources:
  pipelines:
  - pipeline: MyCIAlias  
    project: Fabrikam  
    source: Fabrikam-CI  
    trigger:    
      stages:
      - PreProduction
      - Production

以下示例使用 tags 筛选器进行默认版本计算和触发器。 标记 trigger 使用 AND 运算符。 tags资源定义中的pipeline集不同于 Git 存储库中分支上设置的标记。

resources:
  pipelines:
  - pipeline: MyCIAlias
    project: Fabrikam
    source: Fabrikam-CI
    tags: 
    - Production 
    trigger:
      tags:
      - Production
      - Signed

每当 SmartHotel-CI 资源管道运行时，以下管道都会运行：

• 在某个 releases 分支或分支上运行 main 。
• 用两者 Verified 标记和 Signed。
• 完成 Production 和 PreProduction 阶段。

resources:
  pipelines:
  - pipeline: SmartHotel
    project: otherDevOpsProject
    source: SmartHotel-CI
    trigger:
      branches:
        include:
        - releases/*
        - main
        exclude:
        - topic/*
      tags: 
      - Verified
      - Signed
      stages:
      - Production
      - PreProduction

管道工件下载

可以使用 download YAML 管道中的步骤下载与当前运行或其他 pipeline 资源关联的项目。

项目仅在部署作业中自动下载。 来自当前管道及其所有 pipeline 资源的所有项目都会自动下载，并在每个部署作业开始时可用。 可以通过设置为downloadnone或指定另一个pipeline资源标识符来替代此行为。

在常规生成作业中，项目不会自动下载。 在需要时显式使用 download。

在 download 步骤中，可选 artifact 属性指定项目名称。 如果未指定，所有可用项目都会下载。

可选 patterns 属性定义表示要下载的文件的模式。 有关完整架构信息，请参阅 steps.download 定义。

- job: deploy_windows_x86_agent
  steps:
  - download: SmartHotel
    artifact: WebTier1
    patterns: '**/*.zip'

从pipeline资源下载到 $（PIPELINE） 的项目。WORKSPACE）/<pipeline-identifier/>artifact-identifier<> 文件夹。 有关详细信息，请参阅发布和下载管道工件。 有关下载管道项目的替代方法，请参阅下载项目。

resources:
  pipelines:
  - pipeline: myresourcevars
    source: mypipeline
    trigger: true 

steps:
- script: |
    echo $(resources.pipeline.myresourcevars.pipelineID)
    echo $(resources.pipeline.myresourcevars.runName)
    echo $(resources.pipeline.myresourcevars.runID)
    echo $(resources.pipeline.myresourcevars.runURI)
    echo $(resources.pipeline.myresourcevars.sourceBranch)
    echo $(resources.pipeline.myresourcevars.sourceCommit)
    echo $(resources.pipeline.myresourcevars.sourceProvider)
    echo $(resources.pipeline.myresourcevars.requestedFor)
    echo $(resources.pipeline.myresourcevars.requestedForID)

生成资源

如果有生成项目的 CI 生成系统，则可以将项目与资源一起使用 builds 。

builds 类别是一个可扩展类别。 build 资源可以来自任何外部 CI 系统，例如 Jenkins、TeamCity 或 CircleCI。 可用于 builds 编写扩展以使用生成服务中的项目或引入新类型的服务。

在 build 定义中，version 默认为最新的成功生成。 如果需要，必须显式设置 trigger 。 有关完整的架构信息，请参阅 resources.builds.build 定义。

在以下示例中，Jenkins 是资源类型。

resources:
  builds:
  - build: Spaceworkz
    type: Jenkins
    connection: MyJenkinsServer 
    source: SpaceworkzProj   # name of the Jenkins source project
    trigger: true

downloadBuild 任务

build资源项目不会自动下载到作业/部署作业。 要将 build 资源中的工件作为作业的一部分使用，需要显式添加 downloadBuild 任务。 可以为每个部署或作业自定义下载行为。

该 downloadBuild 任务会自动解析为运行时定义的资源类型的 build 相应下载任务。 从 build 资源下载到 $（PIPELINE） 的项目。WORKSPACE）/<build-identifier>/ folder。

在 downloadBuild 定义中，可以指定从中下载工件的资源。 可选 artifact 属性指定要下载的工件。 如果未指定，则与资源下载关联的所有项目。

可选 patterns 属性定义要下载的最小匹配路径或最小匹配路径列表。 如果为空，则整个项目将下载。 以下示例仅下载 *.zip 文件。

- job: deploy_windows_x86_agent
  steps:
  - downloadBuild: Spaceworkz
    patterns: '**/*.zip'

有关完整架构信息，请参阅 steps.downloadBuild 定义。

存储库资源

使用 repository 关键字让系统了解外部存储库（如果：

• 管道 在另一个存储库中具有模板。
• 你想要将 多存储库签出 与需要服务连接的存储库配合使用。

例如：

resources:
  repositories:
  - repository: common
    type: github
    name: Contoso/CommonTools
    endpoint: MyContosoServiceConnection

有关完整的架构信息，请参阅 resources.repository.repository 定义。

存储库资源类型

Azure Pipelines 支持 git、github和githubenterprisebitbucket存储库类型。

• git 类型引用 Azure Repos Git 存储库。
• GitHub Enterprise 存储库需要 GitHub Enterprise 服务连接进行授权。
• Bitbucket 云存储库需要 Bitbucket 云服务连接进行授权。

下表描述了 repository 资源类型：

存储库资源变量

resources.repositories.<alias>.name
resources.repositories.<alias>.ref
resources.repositories.<alias>.type
resources.repositories.<alias>.id
resources.repositories.<alias>.url

resources:
  repositories:
    - repository: common
      type: git
      ref: main
      name: repo

variables:
  ref: $[ resources.repositories.common.ref ]
  name: $[ resources.repositories.common.name ]
  id: $[ resources.repositories.common.id ]
  type: $[ resources.repositories.common.type ]
  url: $[ resources.repositories.common.url ]

steps:
- bash: |
    echo "name = $(name)"
    echo "ref = $(ref)"
    echo "id = $(id)"
    echo "type = $(type)"
    echo "url = $(url)"

resources.repositories.<alias>.name
resources.repositories.<alias>.ref
resources.repositories.<alias>.type
resources.repositories.<alias>.id
resources.repositories.<alias>.url
resources.repositories.<alias>.version

resources:
  repositories:
    - repository: common
      type: git
      ref: main
      name: Repo

variables:
  ref: $[ resources.repositories.common.ref ]
  name: $[ resources.repositories.common.name ]
  id: $[ resources.repositories.common.id ]
  type: $[ resources.repositories.common.type ]
  url: $[ resources.repositories.common.url ]
  version: $[ resources.repositories.common.version ]

steps:
- bash: |
    echo "name = $(name)"
    echo "ref = $(ref)"
    echo "id = $(id)"
    echo "type = $(type)"
    echo "url = $(url)"
    echo "version = $(version)"

签出存储库的关键字

repository 资源中的存储库不会在作业中自动同步。 可以使用 checkout 关键字提取资源中 repository 定义的存储库。 有关详细信息，请参阅在管道中签出多个存储库。 有关完整的架构信息，请参阅 steps.checkout 定义。

容器资源

可以使用 containers 资源在 CI/CD 管道中使用容器映像。 container 资源可以是公共或专用 Docker 注册表，也可以是 Azure 容器注册表实例。

可以将通用容器资源映像用作作业的一部分，也可以在 容器作业中使用。 如果管道需要一个或多个服务的支持，则还需要创建并连接到 服务容器。 可以使用 卷 在服务之间共享数据。

如果需要使用 Docker 注册表中的映像，可以在不使用关键字的情况下 type 定义通用容器资源。 例如：

resources:         
  containers:
  - container: smartHotel 
    endpoint: myDockerRegistry
    image: smartHotelApp 

有关完整的架构信息，请参阅 resources.containers.container 定义。

Azure 容器注册表资源类型

若要使用 Azure 容器注册表映像，可以使用一级容器资源类型 acr。 可以在作业中使用此资源类型，并启用自动管道触发器。

需要使用 Azure 容器注册表 参与者 或 所有者 权限才能使用自动管道触发器。 有关详细信息，请参阅 Azure 容器注册表角色和权限。

若要使用 acr 资源类型，必须为 Azure 容器注册表指定 azureSubscription、resourceGroup 和 repository 值。 例如：

resources:         
  containers:
  - container: petStore      
    type: acr  
    azureSubscription: ContosoConnection
    resourceGroup: ContosoGroup
    registry: petStoreRegistry
    repository: myPets
    trigger: 
      tags:
        include: 
        - production* 

容器资源变量

将容器定义为资源后，容器映像元数据作为变量传递到管道。 可以在容器部署任务中使用的所有作业中访问映像、注册表和连接详细信息等信息。

容器资源变量适用于 Docker 和 Azure 容器注册表。 不能将容器资源变量用于本地映像容器。 该 location 变量仅适用于 acr 容器资源类型。

以下示例有一个名为 的arm-connection。 有关详细信息，请参阅 Azure 容器注册表、存储库和映像。

resources:
  containers:
  - container: mycontainer
    type: acr
    azureSubscription: arm-connection
    resourceGroup: rg-storage-eastus
    registry: mycontainerregistry
    repository: hello-world
    trigger:
      tags:
      - latest

steps:
- script: echo |
    echo $(resources.container.mycontainer.type)
    echo $(resources.container.mycontainer.registry)
    echo $(resources.container.mycontainer.repository)
    echo $(resources.container.mycontainer.tag)
    echo $(resources.container.mycontainer.digest)
    echo $(resources.container.mycontainer.URI)
    echo $(resources.container.mycontainer.location)

resources:
  packages:
    - package: contoso
      type: npm
      connection: pat-contoso
      name: myname/contoso 
      version: 7.130.88 
      trigger: true

steps:
- getPackage: contoso

resources:
  webhooks:
    - webhook: myWebhookResource
      connection: myWebHookConnection

steps:  
- script: echo ${{ parameters.myWebHookResource.resource.message.title }}

resources:
  webhooks:
    - webhook: MyWebhookTrigger          
      connection: MyWebhookConnection    
      filters:
        - path: repositoryName      
          value: maven-releases     
        - path: action
          value: CREATED

steps:
- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
      Write-Host ${{ parameters.MyWebhookTrigger.repositoryName}}
      Write-Host ${{ parameters.MyWebhookTrigger.component.group}}

{
    "resource": {
        "message": {
            "title": "Hello, world!",
            "subtitle": "I'm using WebHooks!"
        }
    }
}

可跟踪性

Azure Pipelines 为在管道或部署作业级别使用的任何资源提供完全可跟踪性。 Azure Pipelines 显示每个使用资源的管道运行的以下信息：

• 如果资源触发了管道，则触发管道的资源。
• 资源版本和消耗的项目。
• 与每个资源关联的提交。
• 与每个资源关联的工作项。

CI 管道的关联 CD 管道信息

若要提供端到端可跟踪性，可以通过资源跟踪使用特定 CI 管道的 CD 管道 pipelines 。 如果其他管道已使用 CI 管道，可在“运行”视图中看到“关联管道”选项卡。 该视图显示了使用 CI 管道的所有 CD YAML 管道运行以及其中的工件。

环境可跟踪性

管道部署到环境后，可以看到它消耗的资源列表及其关联的提交和工作项。

FAQ

我应该在什么时候使用管道资源、下载快捷方式或下载管道工件任务？

使用 pipelines 资源是使用 CI 管道中的生成工件并配置自动触发器的一种方法。 资源通过显示所使用的版本、生成工件、提交和工作项，使你能够完全了解过程。 定义管道资源时，关联的生成工件会自动下载到部署作业中。

可以使用 download 快捷方式下载生成作业中的工件，或替代部署作业中的下载行为。 有关详细信息，请参阅 steps.download 定义。

下载管道工件任务不提供可跟踪性或触发器，但有时直接使用此任务是有意义的。 例如，你可能有一个脚本任务存储在不同的模板中，该脚本任务需要从生成中下载工件。 或者，你可能不想将管道资源添加到模板中。 为了避免依赖关系，可以使用“下载管道工件”任务将所有生成信息传递给任务。

更新 Docker Hub 映像时，如何触发管道运行？

容器资源触发器不适用于适用于 YAML 管道的 Docker 中心，因此需要 设置经典发布管道。

1. 创建新的 Docker Hub 服务连接。
2. 创建经典发布管道并添加 Docker Hub 生成工件。 设置服务连接，并选择命名空间、存储库、版本和源别名。
3. 选择触发器并将持续部署触发器切换为“启用”。 每次对所选存储库执行 Docker 推送时，都会创建一个发布。
4. 创建新阶段和作业。 添加两个任务：Docker 登录和 Bash。
   • Docker 任务具有 login 操作并登录到 Docker Hub。
   • Bash 任务运行 docker pull <hub-user>/<repo-name>[:<tag>]。

如何验证 Webhook 并排查其中的问题？

1. 创建服务连接。

2. 在 webhooks 部分中引用服务连接并命名 Webhook。

   resources:
     webhooks:
       - webhook: MyWebhookTriggerAlias
         connection: MyServiceConnection
   

3. 运行管道。 Webhook 是在 Azure 中为组织创建的分布式任务。

4. 使用正文中的有效 JSON 对 POST 执行 https://dev.azure.com/<organization>/_apis/public/distributedtask/webhooks/<webhook-name>?api-version=<apiversion> API 调用。 如果收到 200 状态代码响应，则表示 Webhook 已就绪，可供管道使用。

如果收到 500 状态代码响应以及错误 Cannot find webhook for the given webHookId ...，则代码可能位于默认分支以外的分支中。 若要解决此问题：

1. 在管道页上选择编辑。
2. 从更多操作菜单中，选择触发器。
3. 选择 YAML 选项卡，然后选择获取源。
4. 在手动和计划生成的默认分支下，更新功能分支。
5. 选择保存并排队。
6. 此管道成功运行后，使用正文中的有效 JSON 对 POST 执行 https://dev.azure.com/<organization>/_apis/public/distributedtask/webhooks/<webhook-name>?api-version=<apiversion> API 调用。 现在应会收到 200 状态代码响应。

为什么我的资源触发器不起作用？

资源触发器可能执行失败，因为：

• 所提供的服务连接的源无效。
• 触发器未配置或触发器中存在语法错误。
• 触发器条件不匹配。

要查看管道触发器执行失败的原因，请在管道定义页面上选择触发器问题菜单项。 触发器问题 不适用于存储库资源。

在触发器问题页上，错误和警告消息描述触发器失败的原因。

相关内容

• 关于 Azure Pipelines 的资源
• 定义变量
• 添加和使用变量组
• 创建环境并以该环境为目标
• 使用 YAML 管道编辑器
• YAML 架构参考