自定义管道

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

本分步指南介绍自定义管道的常见方法。

先决条件

按照创建你的第一个管道中的说明创建工作管道。

了解 azure-pipelines.yml 文件

管道是使用存储库中的 YAML 文件定义的。 通常，此文件名为 azure-pipelines.yml，位于存储库的根目录中。

导航到 Azure Pipelines 中的“管道”页面，选择你创建的管道，然后在管道的上下文菜单中选择“编辑”，打开管道的 YAML 编辑器。

注意

有关如何在 Azure DevOps 门户中查看和管理管道的说明，请参阅查看和管理管道。

检查 YAML 文件的内容。

 trigger:
 - main

 pool:
   vmImage: 'ubuntu-latest'

 steps:
 - task: Maven@4
   inputs:
     mavenPomFile: 'pom.xml'
     mavenOptions: '-Xmx3072m'
     javaHomeOption: 'JDKVersion'
     jdkVersionOption: '1.11'
     jdkArchitectureOption: 'x64'
     publishJUnitResults: false
     testResultsFiles: '**/surefire-reports/TEST-*.xml'
     goals: 'package'

注意

根据你启动的示例存储库或在 Azure Pipelines 中进行的升级，YAML 文件的内容可能会有所不同。

每当团队将更改推送到存储库的主分支或创建拉取请求时，此管道就会运行。 它在 Microsoft 托管的 Linux 计算机上运行。 管道进程有一个步骤，即运行 Maven 任务。

更改要用于生成的平台

可以在 Microsoft 托管的代理上生成项目，这些代理已包含用于各种开发语言的 SDK 和工具。 或者，可以将自托管代理与所需的特定工具配合使用。

• 在生成中选择“编辑管道操作”或从管道主页中选择“编辑”，导航到管道的编辑器。

• 管道目前在 Linux 代理上运行：

  pool:
    vmImage: "ubuntu-latest"
  

• 要选择其他平台（如 Windows 或 Mac），请更改 vmImage 的值：

  pool:
    vmImage: "windows-latest"
  

  pool:
    vmImage: "macos-latest"
  

• 选择“保存”，然后确认更改，就会看到管道在不同的平台上运行。

添加步骤

可以将更多“脚本”或“任务”作为步骤添加到管道。 任务是预打包的脚本。 可以使用任务来生成、测试、发布或部署应用。 对于 Java，我们使用的 Maven 任务处理测试和发布结果，但也可以使用任务发布代码覆盖率结果。

• 打开管道的 YAML 编辑器。

• 将以下代码片段添加到 YAML 文件的末尾。

  - task: PublishCodeCoverageResults@1
    inputs:
      codeCoverageTool: "JaCoCo"
      summaryFileLocation: "$(System.DefaultWorkingDirectory)/**/site/jacoco/jacoco.xml"
      reportDirectory: "$(System.DefaultWorkingDirectory)/**/site/jacoco"
      failIfCoverageEmpty: true
  

• 选择“保存”以确认更改。

• 可以通过选择生成并转到“测试”和“覆盖率”选项卡来查看测试和代码覆盖率结果。

在多个平台上生成

可以在多个平台上生成和测试项目。 执行此操作的一种方法是使用 strategy 和 matrix。 可以使用变量方便地将数据放入管道的各个部分。 对于此示例，我们将使用变量来传入要使用的图像的名称。

• 在 azure-pipelines.yml 文件中，将以下内容：

  pool:
    vmImage: "ubuntu-latest"
  

  替换为以下内容:

  strategy:
    matrix:
      linux:
        imageName: "ubuntu-latest"
      mac:
        imageName: "macOS-latest"
      windows:
        imageName: "windows-latest"
    maxParallel: 3
  
  pool:
    vmImage: $(imageName)
  

• 选择“保存”，然后确认更改，就会看到生成在三个不同的平台上最多运行三个作业。

每个代理一次只能运行一个作业。 要并行运行多个作业，必须配置多个代理。 还需要足够的并行作业。

使用多个版本生成

要使用该语言的不同版本生成项目，可以使用版本的 matrix 和一个变量。 在此步骤中，可以在单个平台上使用两个不同版本的 Java 生成 Java 项目，也可以在不同平台上运行不同版本的 Java。

注意

不能在上下文中多次使用 strategy。

• 如果要在单个平台和多个版本上生成，请在 Maven 任务之前和 vmImage 之后将以下矩阵添加到 azure-pipelines.yml 文件。

  strategy:
    matrix:
      jdk10:
        jdkVersion: "1.10"
      jdk11:
        jdkVersion: "1.11"
    maxParallel: 2
  

• 然后将 maven 任务中的以下代码行：

  jdkVersionOption: "1.11"
  

  替换为以下代码行：

  jdkVersionOption: $(jdkVersion)
  

• 请确保将 $(imageName) 变量更改回所选平台。

• 如果要在多个平台和版本上生成，请在发布任务之前将 azure-pipelines.yml 文件中的全部内容替换为以下代码片段：

  trigger:
  - main
  
  strategy:
    matrix:
      jdk10_linux:
        imageName: "ubuntu-latest"
        jdkVersion: "1.10"
      jdk11_windows:
        imageName: "windows-latest"
        jdkVersion: "1.11"
    maxParallel: 2
  
  pool:
    vmImage: $(imageName)
  
  steps:
  - task: Maven@4
    inputs:
      mavenPomFile: "pom.xml"
      mavenOptions: "-Xmx3072m"
      javaHomeOption: "JDKVersion"
      jdkVersionOption: $(jdkVersion)
      jdkArchitectureOption: "x64"
      publishJUnitResults: true
      testResultsFiles: "**/TEST-*.xml"
      goals: "package"
  

• 选择“保存”，然后确认更改，就会看到生成在两个不同的平台和 SDK 上运行两个作业。

自定义 CI 触发器

管道触发器会导致管道运行。 可以使用 trigger: 让管道在你将更新推送到分支时运行。 默认情况下，YAML 管道在默认分支（通常是 main）上配置有 CI 触发器。 可以为特定分支或拉取请求验证设置触发器。 对于拉取请求验证触发器，只需将 trigger: 步骤替换为 pr:，如以下两个示例所示。 默认情况下，管道针对每个拉取请求更改运行。

• 如果要设置触发器，请在 azure-pipelines.yml 文件开头添加以下代码片段之一。

  trigger:
    - main
    - releases/*
  

  pr:
    - main
    - releases/*
  

  可以指定分支的全名（例如 main）或前缀匹配通配符（例如 releases/*）。

管道设置

可以通过管道详细信息页面上的“更多操作”菜单查看和配置管道设置。

• 管理安全性 - 管理安全性
• 重命名/移动 - 编辑管道名称和文件夹位置。
• 状态锁屏提醒 - 将状态锁屏提醒添加到存储库
• 删除 - 删除管道，包括所有生成和关联的工件。
• 计划的运行 - “计划的运行”视图

选择“设置”以配置以下管道设置。

在“管道设置”窗格中，可以配置以下设置。

• 处理新的运行请求 - 有时需要阻止新的运行在管道上启动。

  • 默认情况下，新运行请求的处理为“已启用”。 此设置允许对所有触发器类型（包括手动运行）进行标准处理。
  • “暂停的”管道允许处理运行请求，但这些请求会在未实际启动的情况下加入队列。 启用新请求处理后，从队列中的第一个请求开始继续运行处理。
  • “禁用的”管道阻止用户启动新运行。 应用此设置时，也会禁用所有触发器。 所有使用禁用管道的生成策略都会在 PR 概述窗口中的生成策略旁边显示“无法排队生成”消息，并且生成策略的状态将中断。

• YAML 文件路径 - 如果你需要指示管道使用不同的 YAML 文件，可以指定该文件的路径。 如果需要移动/重命名 YAML 文件，此设置也很有用。

• 自动链接此运行中包含的工作项 - 与给定管道运行关联的更改可能具有与之关联的工作项。 选择此选项可将这些工作项链接到运行。 选择“自动链接此运行中包含的工作项”时，必须指定特定分支或 * 以表示所有分支（默认值）。 如果指定分支，则工作项仅与该分支的运行相关联。 如果指定 *，则会为所有运行关联工作项。

  

  • 要在运行失败时获取通知，请参阅如何管理团队的通知

管理安全性

可以通过管道登陆页面上的“更多操作”在项目级别配置管道安全性，或者通过管道详细信息页面在管道级别配置管道安全性。

要支持管道操作的安全性，可以将用户添加到内置安全组、为用户或组设置单独的权限，或将用户添加到预定义的角色。 可以在 Web 门户中从用户或管理员上下文管理 Azure Pipelines 的安全性。 有关配置管道安全性的详细信息，请参阅管道权限和安全角色。

失败时创建工作项

YAML 管道不像经典生成管道一样具有失败时创建工作项设置。 经典生成管道是单阶段的，“失败时创建工作项”适用于整个管道。 YAML 管道可以是多阶段的，管道级别设置可能不合适。 要在 YAML 管道中实现“失败时创建工作项”，可以在管道中的所需位置使用工作项 - 创建 REST API 调用或 Azure DevOps CLI az boards work-item create 命令等方法。

上一示例有两个作业。 第一个作业表示管道的工作，但如果它失败，第二个作业将运行，并在管道所在的同一项目中创建 bug。

# When manually running the pipeline, you can select whether it
# succeeds or fails.
parameters:
- name: succeed
  displayName: Succeed or fail
  type: boolean
  default: false

trigger:
- main

pool:
  vmImage: ubuntu-latest

jobs:
- job: Work
  steps:
  - script: echo Hello, world!
    displayName: 'Run a one-line script'

  # This malformed command causes the job to fail
  # Only run this command if the succeed variable is set to false
  - script: git clone malformed input
    condition: eq(${{ parameters.succeed }}, false)

# This job creates a work item, and only runs if the previous job failed
- job: ErrorHandler
  dependsOn: Work
  condition: failed()
  steps: 
  - bash: |
      az boards work-item create \
        --title "Build $(build.buildNumber) failed" \
        --type bug \
        --org $(System.TeamFoundationCollectionUri) \
        --project $(System.TeamProject)
    env: 
      AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
    displayName: 'Create work item on failure'

注意

Azure Boards 允许使用多个不同的流程（例如敏捷或基本）配置工作项跟踪。 每个进程都有不同的工作项类型，并非每个工作项类型在每个进程中都可用。 有关每个进程支持的工作项类型的列表，请参阅工作项类型 (WIT)。

前面的示例使用运行时参数来配置管道是成功还是失败。 手动运行管道时，可以设置 succeed 参数的值。 管道第一个作业中的第二个 script 步骤将计算 succeed 参数并且仅在 succeed 设置为 false 时才运行。

管道中的第二个作业依赖于第一个作业，并且仅在第一个作业失败时运行。 第二个作业使用 Azure DevOps CLI az boards work-item create 命令创建 bug。 有关从管道运行 Azure DevOps CLI 命令的详细信息，请参阅在 YAML 管道中运行命令。

此示例使用两个作业，但这种方法可以跨多个阶段使用。

注意

还可以使用市场扩展，例如发布失败时创建 Bug，该扩展支持 YAML 多阶段管道。

后续步骤

你已了解自定义管道的基础知识。 接下来，建议详细了解如何自定义所用语言的管道：

• .NET Core
• 容器
• Go
• Java
• Node.js
• Python

或者，要将 CI 管道扩展到 CI/CD 管道，包括一个部署作业，其中包含将应用部署到环境的步骤。

要详细了解本指南中的主题，请参阅作业、任务、任务目录、变量、触发器或故障排除。

若要了解可在 YAML 管道中执行的其他操作，请参阅 YAML 架构参考。