在 YAML 中定义资源

  • 项目

Azure DevOps Services

YAML 中的资源表示管道、生成、存储库、容器、包和 Webhook 的源。 资源还提供管道中使用的服务的完整可跟踪性，包括版本、项目、关联的提交和工作项。 定义资源时，可以在管道中的任何位置使用它。 通过订阅资源上的触发事件，可以完全自动化DevOps工作流。

有关详细信息，请参阅“关于资源”

架构

resources:
  pipelines: [ pipeline ]  
  builds: [ build ]
  repositories: [ repository ]
  containers: [ container ]
  packages: [ package ]
  webhooks: [ webhook ]

变量

当资源触发管道时，将设置以下变量：

resources.triggeringAlias
resources.triggeringCategory

如果资源未触发管道运行，则这些值为空。 Build.Reason变量必须ResourceTrigger供这些值设置。

pipelines定义资源

如果有生成项目的管道，可以通过定义 pipelines 资源来使用项目。 pipelines是仅用于Azure Pipelines的专用资源。 还可以在 CD 工作流的管道资源上设置触发器。

在资源定义中，是一个唯一值， pipeline 可用于稍后引用管道资源。 source 是生成项目的管道的名称。 使用定义的 pipeline 标签从管道的其他部分引用管道资源，例如在使用管道资源变量或下载项目时。

有关下载管道的替代方法，请参阅管道Artifacts中的任务。

resources:        # types: pipelines | builds | repositories | containers | packages
  pipelines:
  - pipeline: string  # identifier for the resource used in pipeline resource variables
    project: string # project for the source; optional for current project
    source: string  # name of the pipeline that produces an artifact
    version: string  # the pipeline run number to pick the artifact, defaults to latest pipeline successful across all stages; Used only for manual or scheduled triggers
    branch: string  # branch to pick the artifact, optional; defaults to all branches; Used only for manual or scheduled triggers
    tags: [ string ] # list of tags required on the pipeline to pickup default artifacts, optional; Used only for manual or scheduled triggers
    trigger:     # triggers aren't enabled by default unless you add trigger section to the resource
      branches:  # branch conditions to filter the events, optional; Defaults to all branches.
        include: [ string ]  # branches to consider the trigger events, optional; Defaults to all branches.
        exclude: [ string ]  # branches to discard the trigger events, optional; Defaults to none.
      tags: [ string ]  # list of tags to evaluate for trigger event, optional
      stages: [ string ] # list of stages to evaluate for trigger event, optional

重要

定义资源触发器时，如果其管道资源来自同一存储库， (将自) 称为当前管道，则触发操作将遵循引发事件的同一分支并提交。 但是，如果管道资源来自不同存储库，则当前管道会在自存储库的默认分支上触发。

项目版本的评估

资源管道项目的版本取决于管道的触发方式。

如果管道由于手动触发或计划运行而运行，则项目版本由versionbranch值和tags属性定义。

指定的属性 项目版本
version 具有指定运行编号的生成中的项目
branch 指定分支上执行的最新生成中的项目
tags 列表 具有所有指定标记的最新生成中的项目
branch 和 tags 列表 在指定分支上执行的最新生成中的项目 ，并且 具有所有指定标记
无 所有分支中最新生成的项目

接下来举例说明。 假设管道包含以下资源定义。

resources:
  pipelines:
  - pipeline: MyCIAlias
    project: Fabrikam
    source: Farbrikam-CI
    branch: main      ### This branch input cannot have wild cards. It is used for evaluating default version when pipeline is triggered manually or scheduled.
    tags:               ### These tags are used for resolving default version when the pipeline is triggered manually or scheduled
    - Production        ### Tags are AND'ed
    - PreProduction

手动触发管道运行时，管道的项目 MyCIAlias 版本是分支上 main 完成的最新生成之一，并且具有 Production 标记 PrepProduction 。

当管道由于其中一个资源管道完成而触发时，项目的版本是触发管道之一。 version忽略值branch和tags属性。

指定的触发器 业务成效
branches 每当资源管道成功完成分支上运行 include 时，就会触发当前管道的新运行
tags 每当资源管道成功完成包含 所有 指定标记的运行时，都会触发当前管道的新运行
stages 每当资源管道成功执行指定的资源管道时，就会触发当前管道的新运行 stages
branches、tags 和 stages 每当资源管道运行满足 所有 分支、标记和阶段条件时，都会触发当前管道的新运行
trigger: true 每当资源管道成功完成运行时，就会触发当前管道的新运行
无 资源管道成功完成运行后，不会触发当前管道的新运行

接下来举例说明。 假设管道包含以下资源定义。

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

每当管道在一个分支或main分支上运行时SmartHotel，管道就会运行，并标记了两Verified者，并且Signed已完成和PreProductionProduction阶段。releases

download 用于管道

从当前管道和所有资源的所有项目都会自动下载并在 pipeline 每个 deployment 作业开始时提供。 可以重写此行为。 有关详细信息，请参阅管道Artifacts。 不会自动下载常规的“作业”项目。 在需要时显式使用 download 。

steps:
- download: [ current | pipeline resource identifier | none ] # disable automatic download if "none"
  artifact: string ## artifact name, optional; downloads all the available artifacts if not specified
  patterns: string # patterns representing files to include; optional

Artifacts从pipeline资源下载到$(PIPELINE.WORKSPACE)/<pipeline-identifier>/<artifact-identifier>文件夹。

管道资源变量

在每个运行中，管道资源的元数据以 预定义变量的形式提供给所有作业。 是 <Alias> 为管道资源提供标识符。 管道资源变量仅在运行时可用。

resources.pipeline.<Alias>.projectID
resources.pipeline.<Alias>.pipelineName
resources.pipeline.<Alias>.pipelineID
resources.pipeline.<Alias>.runName
resources.pipeline.<Alias>.runID
resources.pipeline.<Alias>.runURI
resources.pipeline.<Alias>.sourceBranch
resources.pipeline.<Alias>.sourceCommit
resources.pipeline.<Alias>.sourceProvider
resources.pipeline.<Alias>.requestedFor
resources.pipeline.<Alias>.requestedForID

builds定义资源

如果你有一个生成项目的外部 CI 生成系统，则可以使用 builds 具有资源的项目。 builds资源可以是任何外部 CI 系统，例如 Jenkins、TeamCity、CircleCI 等。

resources:        # types: pipelines | builds | repositories | containers | packages
  builds:
  - build: string   # identifier for the build resource
    type: string   # the type of your build service like Jenkins, circleCI etc.
    connection: string   # service connection for your build service.
    source: string   # source definition of the build
    version: string   # the build number to pick the artifact, defaults to Latest successful build
    trigger: boolean    # Triggers aren't enabled by default and should be explicitly set

builds 是一个可扩展类别。 可以编写扩展以使用生成服务中的项目，并将新类型的服务作为一 builds部分引入。 Jenkins 是一种资源类型 builds。

重要

仅托管的 Jenkins 支持触发器，其中Azure DevOps与 Jenkins 服务器具有视线。

downloadBuild 生成任务

可以使用任务将资源中的 build 项目用作作业 downloadBuild 的一部分。 根据定义的资源类型 build ，此任务会在运行时自动解析为服务的相应下载任务。

Artifacts从build资源下载到$(PIPELINE.WORKSPACE)/<build-identifier>/文件夹。

重要

build 不会在作业/deploy-jobs 中自动下载资源项目。 需要显式添加 downloadBuild 用于使用项目的任务。

- downloadBuild: string # identifier for the resource from which to download artifacts
  artifact: string # artifact to download; if left blank, downloads all artifacts associated with the resource provided
  patterns: string | [ string ] # a minimatch path or list of [minimatch paths](tasks/file-matching-patterns.md) to download; if blank, the entire artifact is downloaded

repositories定义资源

如果管道 在另一个存储库中具有模板，或者想要将 多存储库签出 与需要服务连接的存储库配合使用，则必须让系统知道该存储库。 使用 repository 关键字可以指定外部存储库。

resources:
  repositories:
  - repository: string  # identifier (A-Z, a-z, 0-9, and underscore)
    type: enum  # see the following "Type" topic
    name: string  # repository name (format depends on `type`)
    ref: string  # ref name to use; defaults to 'refs/heads/main'
    endpoint: string  # name of the service connection to use (for types that aren't Azure Repos)
    trigger:  # CI trigger for this repository, no CI trigger if skipped (only works for Azure Repos)
      branches:
        include: [ string ] # branch names which trigger a build
        exclude: [ string ] # branch names which won't
      tags:
        include: [ string ] # tag names which trigger a build
        exclude: [ string ] # tag names which won't
      paths:
        include: [ string ] # file paths which must match to trigger a build
        exclude: [ string ] # file paths which won't trigger a build

类型

Pipelines支持存储库类型的以下值：git、github、githubenterprise和bitbucket。 类型git引用 Azure Repos Git 存储库。

指定类型 业务成效 示例
type: git 该值 name 引用同一项目中的另一个存储库。 name: otherRepo 若要引用同一组织中的另一个项目中的存储库，请使用该项目的名称作为前缀。 例如 name: OtherProject/otherRepo。
type: github 该值name是GitHub存储库的完整名称，包括用户或组织。 name: Microsoft/vscode
type: githubenterprise 该值name是GitHub Enterprise存储库的完整名称，包括用户或组织。 name: Microsoft/vscode
type: bitbucket 该值 name 是 Bitbucket 云存储库的完整名称，包括用户或组织。 name: MyBitbucket/vscode

GitHub Enterprise存储库需要GitHub Enterprise服务连接进行授权。

Bitbucket Cloud 存储库需要 Bitbucket 云服务连接 进行授权。

用于 checkout 使用存储库

使用 checkout 关键字使用定义为资源的一部分的 repository 存储库。

架构

steps:
- checkout: string  # identifier for your repository resource
  clean: boolean  # if true, execute `execute git clean -ffdx && git reset --hard HEAD` before fetching
  fetchDepth: number  # the depth of commits to ask Git to fetch; defaults to no limit
  lfs: boolean  # whether to download Git-LFS files; defaults to false
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules; defaults to not checking out submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1); defaults to a directory called `s`
  persistCredentials: boolean  # if 'true', leave the OAuth token in the Git config after the initial fetch; defaults to false

资源中的Reposrepository不会在作业中自动同步。 用于 checkout 提取存储库作为作业的一部分。

有关详细信息，请参阅 管道中的多个存储库。

containers定义资源

如果需要使用容器映像作为持续集成/持续交付的一部分， (CI/CD) 管道，则可以使用 containers它。 容器资源可以是公共或专用 Docker 注册表，也可以是Azure 容器注册表。

如果需要在管道中使用 Docker 注册表中的映像，则可以定义泛型容器资源 (不需要 type 关键字) 。

resources:
  containers:
  - container: string  # identifier (A-Z, a-z, 0-9, and underscore)
    image: string  # container image name
    options: string  # arguments to pass to container at startup
    endpoint: string  # reference to a service connection for the private registry
    env: { string: string }  # list of environment variables to add
    ports: [ string ] # ports to expose on the container
    volumes: [ string ] # volumes to mount on the container
    mapDockerSocket: bool # whether to map in the Docker daemon socket; defaults to true
    mountReadOnly:  # volumes to mount read-only - all default to false
      externals: boolean  # components required to talk to the agent
      tasks: boolean  # tasks required by the job
      tools: boolean  # installable tools like Python and Ruby
      work: boolean # the work directory

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

可以使用用于 Azure 容器注册表 (ACR) 的一类容器资源类型来使用 ACR 映像。 此资源类型可用作作业的一部分，还可用于启用自动管道触发器。

resources:          # types: pipelines | repositories | containers | builds | packages
  containers:
  - container: string # identifier for the container resource      
    type: string # type of the registry like ACR, GCR etc. 
    azureSubscription: string # Azure subscription (ARM service connection) for container registry;
    resourceGroup: string # resource group for your ACR
    registry: string # registry for container images
    repository: string # name of the container image repository in ACR
    trigger: # Triggers aren't enabled by default and need to be set explicitly
      enabled: boolean # set to 'true' to trigger on all image tags if 'tags' is unset.
      tags:
        include: [ string ]  # image tags to consider the trigger events, optional; defaults to any new tag
        exclude: [ string ]  # image tags on discard the trigger events, optional; defaults to none

注意

用于为所有映像标记启用容器触发器的语法 (enabled: 'true') 不同于用于其他资源触发器的语法。 请密切关注对特定资源使用正确的语法。

容器资源变量

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

resources.container.<Alias>.type
resources.container.<Alias>.registry
resources.container.<Alias>.repository
resources.container.<Alias>.tag 
resources.container.<Alias>.digest
resources.container.<Alias>.URI
resources.container.<Alias>.location

位置变量仅适用于 ACR 容器资源的类型。

packages定义资源

可以将NuGet和npm GitHub包用作 YAML 管道中的资源。

指定package资源时，请将包设置为NuGet或npm。 还可以在发布新的包版本时启用自动化管道触发器。

若要使用GitHub包，请使用个人访问令牌 (基于 PAT) 的身份验证，并创建使用 PAT 的GitHub服务连接。

默认情况下，包不会自动下载到作业中。 若要下载，请使用 getPackage。

resources:
  packages:
    - package: myPackageAlias # alias for the package resource
      type: Npm # type of the package NuGet/npm
      connection: GitHubConnectionName # GitHub service connection with the PAT type
      name: nugetTest/nodeapp # <Repository>/<Name of the package>
      version: 1.0.1 # Version of the package to consume; Optional; Defaults to latest
      trigger: true # To enable automated triggers (true/false); Optional; Defaults to no triggers

webhooks定义资源

与其他资源 (（例如管道、容器、生成和包）) 可以使用项目并启用自动触发器。 但是，不能基于其他外部事件或服务自动执行部署过程。 利用该 webhooks 资源，可以将管道与任何外部服务集成，并自动执行工作流。 可以通过其 Webhook (GitHub、GitHub Enterprise、Nexus、Artifactory 等) 订阅任何外部事件并触发管道。

执行以下步骤以配置 Webhook 触发器。

  1. 在外部服务上设置 Webhook。 创建 Webhook 时，需要提供以下信息：

    • 请求 URL - https://dev.azure.com/<ADO Organization>/_apis/public/distributedtask/webhooks/<WebHook Name>?api-version=6.0-preview
    • 机密 - 可选。 如果需要保护 JSON 有效负载，请提供 机密 值。

  2. 创建新的“传入 Webhook”服务连接。 此连接是新引入的服务连接类型，可用于定义以下重要信息：

    • Webhook 名称：Webhook 的名称应与在外部服务中创建的 Webhook 相匹配。
    • HTTP 标头 - 请求中包含有效负载的 HMAC-SHA1 哈希值的请求中 HTTP 标头的名称，用于请求验证。 例如，对于GitHub，请求标头为“X-Hub-Signature”。
    • 机密 - 机密用于验证有效负载的 HMAC-SHA1 哈希，用于验证传入请求 (可选) 。 如果在创建 Webhook 时使用了机密，则必须提供相同的密钥。

    Incoming Webhook Service connection

  3. YAML 管道中引入了名为 webhooks 的新资源类型。 若要订阅 Webhook 事件，请在管道中定义 Webhook 资源，并将其指向传入 Webhook 服务连接。 还可以根据 JSON 有效负载数据在 Webhook 资源上定义更多筛选器，以自定义每个管道的触发器。 使用作业中的变量形式的有效负载数据。

  4. 每当传入 Webhook 服务连接收到 Webhook 事件时，订阅 Webhook 事件的所有管道都会触发新的运行。 可以使用格式在作业中使用 JSON 有效负载数据 ${{ parameters.<WebhookAlias>.<JSONPath>}}

resources:
  webhooks:
    - webhook: MyWebhookTriggerAlias           ### Webhook alias
      connection: IncomingWebhookConnection    ### Incoming webhook service connection
      filters:                                 ### List of JSON parameters to filter; Parameters are AND'ed
        - path: JSONParameterPath              ### JSON path in the payload
          value: JSONParameterExpectedValue    ### Expected value in the path provided

Webhook 基于一流资源不支持的任何外部 Webhook 事件自动执行工作流。 管道、生成、容器和包等资源。 此外，对于Azure DevOps无法查看进程的本地服务，可以在服务上配置 Webhook 并自动触发管道。

创建运行对话框中资源的手动版本选取器

手动触发 CD YAML 管道时，我们会根据提供的输入自动评估管道中定义的资源的默认版本。 但是，可以在创建运行时选择与资源版本选取器不同的版本。

  1. 在 “创建运行 ”窗格中，选择“ 资源”。 可以看到此管道中消耗的资源列表。

  2. 选择资源并从可用的版本列表中选择特定版本。 管道、生成、存储库、容器和包资源支持资源版本选取器。

    Pipeline Version Picker

对于管道资源，可以看到所有分支中的所有可用运行。 根据管道编号或分支搜索它们。 然后，选择成功、失败或正在进行的运行。 这种灵活性可以确保可以运行 CD 管道（如果确定它已生成所需的所有项目）。 由于 CI 运行中不相关的阶段失败，无需等待 CI 运行完成或重新运行。 但是，我们只考虑在评估计划触发器的默认版本时或者不使用手动版本选取器时，才考虑成功完成 CI 运行。

对于无法提取可用版本的资源（如GitHub包），我们会在版本选取器中显示一个文本框，以便提供要选取的运行版本。

授权 YAML 管道

必须先对资源进行授权，然后才能使用资源。 资源所有者控制可以访问该资源的用户和管道。 管道必须获得使用资源的授权。 请参阅以下方法来授权 YAML 管道。

  • 转到资源的管理体验。 例如，变量组和安全文件在Pipelines下的“库”页中管理。 代理池和服务连接在Project设置中管理。 可以在此处授权 所有管道 访问该资源。 如果不需要限制对资源的访问（例如测试资源），则此授权非常方便。

  • 首次创建管道时，如果属于该资源 的用户 角色的成员，则 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 模板扩展。 设置所需的模板审批可增强安全性。 确保资源仅在模板的特定条件下使用。 详细了解如何使用模板和资源 增强管道安全性 。

可跟踪性

我们为管道或部署作业级别使用的任何资源提供完全可跟踪性。

管道可跟踪性

对于每个管道运行，我们都会显示以下信息。

  • 如果资源由资源触发，则触发管道的资源。

    Resource trigger in a pipeline

  • 使用的资源版本和项目。

    Consumed artifacts in pipeline run

  • 与每个资源关联的提交。

    Commits in pipeline run

  • 与每个资源关联的工作项。

环境可跟踪性

每当管道部署到环境时，都可以看到消耗的资源列表。 以下视图包括部署作业中包含的资源及其关联的提交和工作项。

Commits in environment

在 CI 管道中显示关联的 CD 管道信息

若要提供端到端可跟踪性，可以跟踪哪些 CD 管道正在使用提供 CI 管道。 可以看到 CD YAML 管道运行的列表，其中 CI 管道运行通过 pipeline 资源使用。 如果其他管道使用 CI 管道，则运行视图中会显示“关联的管道”选项卡。 在这里，可以找到使用管道和项目的所有管道运行。

CD pipelines information in CI pipeline

YAML 资源触发器问题支持和可跟踪性

当管道触发器无法执行时，可能会造成混淆。 我们在管道定义页中添加了一个名为 “触发器问题”的新菜单项，你可以在其中了解触发器未执行的原因。 若要访问此页面，请打开管道历史记录。 触发器问题 仅适用于非存储库资源。

Select Trigger Issues from the navigation.

出于以下原因，资源触发器可能无法执行。

  • 如果所提供的服务连接源无效，或者触发器中存在任何语法错误，则不会配置触发器，从而导致错误。

  • 如果未匹配触发器条件，则不会执行触发器。 将显示警告，以便你可以了解条件不匹配的原因。

    Trigger issues supportability

后续步骤

添加和使用变量组

常见问题

为何应使用管道 resources 而不是 download 快捷方式？

pipelines使用资源是使用 CI 管道中的项目并配置自动触发器的方法。 通过显示使用的版本、项目、提交和工作项，资源可让你完全了解该过程。 定义管道资源时，会在部署作业中自动下载关联的项目。

You can choose to download the artifacts in build jobs or to override the download behavior in deployment jobs with download. 该download任务在内部使用下载管道Artifacts任务。

为何应使用resources而不是下载管道Artifacts任务？

直接使用下载管道Artifacts任务时，缺少可跟踪性和触发器。 有时直接使用下载管道Artifacts任务是有意义的。 例如，你可能有一个脚本任务存储在不同的模板中，并且脚本任务需要从生成下载项目。 或者，你可能不知道使用模板的人是否想要添加管道资源。 若要避免依赖项，可以使用下载管道Artifacts任务将所有生成信息传递给任务。

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

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

  1. 创建新的Docker Hub服务连接。

  2. 创建经典发布管道并添加Docker Hub项目。 设置服务连接。 选择命名空间、存储库、版本和源别名。

    Add a Docker Hub artifact.

  3. 选择触发器并将连续部署触发器切换为 “启用”。 每次将 Docker 推送到所选存储库时，都会创建发布。

  4. 创建新的阶段和作业。 添加两个任务：Docker 登录名和 Bash：

  • Docker 任务具有操作login，并将你记录到Docker Hub。

  • Bash 任务运行 docker pull <hub-user>/<repo-name>[:<tag>]。 将值repo-nametag替换为hub-user值。

    Add Docker login and Bash tasks.