自訂您的管線

  • 發行項

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'

注意

YAML 檔案的內容可能會根據您開始使用的範例存放庫或 Azure Pipelines 中的升級而有所不同。

每當您的小組將變更推送至存放庫的主要分支，或建立提取要求時，就會執行此管線。 它會在 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 管線預設會以預設分支上的 CI 觸發程式進行設定（通常是 main）。 您可以為特定分支或提取要求驗證設定觸發程式。 針對提取要求驗證觸發程式，只要將步驟取代 trigger: 為 pr: ，如下所示的兩個範例所示。 根據預設，管線會針對每個提取要求變更執行。

  • 如果您想要設定觸發程式，請在檔案 azure-pipelines.yml 開頭新增下列其中一個代碼段。

    trigger:
  - main
  - releases/*

    pr:
  - main
  - releases/*

    您可以指定分支的完整名稱（例如 main）， 或前置詞比對通配符 （例如 ， releases/*。

管線設定

您可以從管線詳細數據頁面上的 [更多動作] 功能表檢視和設定管線設定。

Screenshot of pipeline settings and more actions menu.

選擇 [設定]，以設定下列管線設定。

Screenshot of pipeline settings page.

您可以從 [ 管線設定 ] 窗格中設定下列設定。

  • 處理新的執行要求 - 有時候您會想要防止新的執行開始於管線上。

    • 根據預設，新執行要求的處理會 啟用。 此設定允許標準處理所有觸發程式類型，包括手動執行。
    • 暫停的 管線允許處理執行要求，但這些要求會排入佇列，而不會實際啟動。 啟用新的要求處理時，從佇列中的第一個要求開始執行處理。
    • 停用的 管線可防止用戶啟動新的執行。 套用此設定時，也會停用所有觸發程式。 所有使用已停用管線的建置原則都會在PR概觀視窗中顯示 [無法排入佇列建置] 訊息，而組建原則的狀態將會中斷。

  • YAML 檔案路徑 - 如果您需要指示管線使用不同的 YAML 檔案，您可以指定該檔案的路徑。 如果您需要移動/重新命名YAML檔案，此設定也很有用。

  • 自動連結此執行 中包含的工作專案 - 與指定管線執行相關聯的變更可能會有與其相關聯的工作專案。 選取此選項可將這些工作項目連結至執行。 選取 [自動連結此執行中包含的工作專案] 時，您必須指定特定分支，或*針對預設的所有分支。 如果您指定分支，工作專案只會與該分支的執行相關聯。 如果您指定 *，工作專案會針對所有執行相關聯。

    Screenshot of setting to automatically link work items included in this run.

管理安全性

您可以從管線登陸頁面上的 [更多動作] 和管線詳細數據頁面上的管線層級，在專案層級上設定管線安全性。

Screenshot of pipeline security menu options.

若要支援管線作業的安全性，您可以將使用者新增至內建安全組、設定使用者或群組的個別許可權，或將使用者新增至預先定義的角色。 您可以從使用者或系統管理員內容管理入口網站中的 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 可讓您使用數個不同的程式來設定工作項目追蹤，例如 Agile 或 Basic。 每個進程都有不同的工作項目類型，而且每個程式都無法使用每個工作項目類型。 如需每個程式所支援的工作項目類型清單，請參閱工作項目類型（WIT）。

上述範例會使用 運行時間參數 來設定管線是否成功或失敗。 手動執行管線時，您可以設定 參數的值 succeed 。 管線第一個作業中的第二 script 個步驟會評估 參數， succeed 而且只有在 設定為 false 時 succeed 才會執行。

管線中的第二個作業相依於第一個作業，而且只有在第一個作業失敗時才會執行。 第二個作業會使用 Azure DevOps CLI az boards work-item create 命令來建立 Bug。 如需從管線執行 Azure DevOps CLI 命令的詳細資訊，請參閱 在 YAML 管線中執行命令。

此範例使用兩個作業，但這個相同的方法可以跨 多個階段使用。

注意

您也可以使用市集擴充功能，例如 在發行失敗 時建立 Bug，其支援 YAML 多階段管線。

下一步

您已瞭解自定義管線的基本概念。 接下來，建議您深入瞭解如何針對您使用的語言自定義管線：

或者，若要將您的 CI 管線成長為 CI/CD 管線，請包含 部署作業 ，其中包含將應用程式部署至 環境的步驟。

若要深入瞭解本指南中的主題，請參閱作業、工作、工作目錄、變數、觸發程式或疑難解答。

若要瞭解您可以在 YAML 管線中執行的其他動作，請參閱 YAML 架構參考。