共用方式為


自訂您的管線

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
    
  • 選取 [ 儲存 ],然後確認變更。

  • 您可以選取組建並移至 [測試和涵蓋範圍] 索引標籤,以檢視測試和程式代碼涵蓋範圍結果。

跨多個平台建置

您可以在多個平臺上建置和測試專案。 其中一種方法是 使用 strategymatrix。 您可以使用變數,輕鬆地將數據放入管線的各個部分。 在此範例中,我們將使用變數來傳入我們想要使用的映像名稱。

  • 在您的 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/*

管線設定

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

管線設定和更多動作功能表的螢幕快照。

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

管線設定頁面的螢幕快照。

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

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

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

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

    設定為自動連結此執行中包含的工作項目的螢幕快照。

管理安全性

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

管線安全性功能表選項的螢幕快照。

若要支援管線作業的安全性,您可以將使用者新增至內建安全組、設定使用者或群組的個別許可權,或將使用者新增至預先定義的角色。 您可以從使用者或系統管理員內容管理入口網站中的 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 管線中執行命令。

YAML 管線在失敗設定上沒有建立工作專案,例如傳統建置管線。 傳統建置管線是單一階段,而 在失敗 時建立工作專案會套用至整個管線。 YAML 管線可以是多階段,而且管線層級設定可能不適合。 若要在 YAML 管線中的失敗時實作建立工作專案,您可以使用管線中所需點的工作專案 - 建立 REST API 呼叫。

下列範例有兩個作業。 第一個作業代表管線的工作,但如果它失敗,第二個作業就會執行,並在與管線相同的專案中建立 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: |
      curl \
        -X POST \
        -H 'Authorization: Basic $(System.AccessToken)' \
        -H 'Content-Type: application/json-patch+json' \
        -d '[
              {
                "op": "add",
                "path": "/fields/System.Title",
                "from": null,
                "value": "git clone failed"
              }
            ]' \
        "$(System.CollectionUri)$(System.TeamProject)/_apis//wit/workitems/$Bug?api-version=7.1-preview.3
"
    env:
        SYSTEM_ACCESSTOKEN: $(System.AccessToken)
    displayName: 'Create work item on failure'

注意

Azure Boards 可讓您使用數個不同的程式來設定工作項目追蹤,例如 Agile 或 Basic。 每個進程都有不同的工作項目類型,而且每個程式都無法使用每個工作項目類型。 如需每個程式所支援的工作項目類型清單,請參閱工作項目類型(WIT)。

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

管線中的第二個作業相依於第一個作業,而且只有在第一個作業失敗時才會執行。 第二個作業會使用 Azure DevOps API az boards work-item create 命令來建立 Bug。

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

注意

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

下一步

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

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

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

若要了解您可以在 YAML 管線中執行的其他動作,請參閱 YAML 結構描述參考