自訂您的管線
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/*
。
管線設定
您可以從管線詳細數據頁面上的 [更多動作] 功能表檢視和設定管線設定。
- 管理安全性 - 管理安全性
- 重新命名/移動 - 編輯您的管線名稱和資料夾位置。
- 狀態徽章 將狀態徽章 - 新增至您的存放庫
- 刪除 - 刪除 管線,包括所有組建和相關聯的成品。
- 排程執行 - 排程的執行檢視
選擇 [設定 ] 以設定下列管線設定。
您可以從 [ 管線設定 ] 窗格中設定下列設定。
處理新的執行要求 - 有時候您會想要防止新的執行開始於管線上。
- 根據預設,新執行要求的處理會 啟用。 此設定允許標準處理所有觸發程式類型,包括手動執行。
- 暫停的 管線允許處理執行要求,但這些要求會排入佇列,而不會實際啟動。 啟用新的要求處理時,從佇列中的第一個要求開始執行處理。
- 停用的 管線可防止用戶啟動新的執行。 套用此設定時,也會停用所有觸發程式。 所有使用已停用管線的建置原則都會在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 結構描述參考。