建置 Azure Repos Git 或 TFS Git 存放庫

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

注意

Microsoft Visual Studio Team Foundation Server 2018 和舊版在命名方面有下列差異:

  • 組建和發行的 管線稱為 定義
  • 執行 稱為 組建
  • 服務聯機 稱為 服務端點
  • 階段 稱為 環境
  • 作業 稱為 階段

Azure Pipelines 可以自動建置並驗證每個提取要求,並認可至您的 Azure Repos Git 存放庫。

選擇要建置的存放庫

您可以先選取存放庫,然後在該存放庫中建立 YAML 檔案,以建立新的管線。 YAML 檔案所在的存放庫稱為 self 存放庫。 根據預設,這是管線所建置的存放庫。

您稍後可以設定管線來簽出不同的存放庫或多個存放庫。 若要瞭解如何執行這項操作,請參閱 多存放庫簽出

TFS 中無法使用YAML管線。

Azure Pipelines 必須獲得存放庫的存取權,才能觸發其組建,並在組建期間擷取其程式碼。 一般而言,管線可以存取相同專案中的存放庫。 但是,如果您想要存取不同專案中的存放庫,則必須更新授與作業 存取令牌的許可權。

CI 觸發程式

持續整合 (CI) 觸發程式會在您推送更新至指定的分支或推送指定的標記時,導致管線執行。

YAML 管線預設會在所有分支上使用 CI 觸發程式來設定,除非已啟用 Azure DevOps 短期衝刺 227引進的停用隱含 YAML CI 觸發程式設定。 您可以在組織層級或專案層級設定停用隱含 YAML CI 觸發程式設定。 啟用 [停用隱含 YAML CI 觸發程式] 設定時,如果 YAML 管線沒有trigger區段,就不會啟用 YAML 管線的 CI 觸發程式。 預設不會啟用停用隱含 YAML CI 觸發程式

分支

您可以使用簡單的語法來控制哪些分支會取得 CI 觸發程式:

trigger:
- main
- releases/*

您可以指定分支的完整名稱(例如 main), 或通配符 (例如 , releases/*。 如需通配符語法的相關信息,請參閱 通配符

注意

您無法在觸發程式中使用 變數 ,因為變數會在運行時間評估(觸發程式引發之後)。

注意

如果您使用 範本 來撰寫 YAML 檔案,則您只能在管線的主要 YAML 檔案中指定觸發程式。 您無法在樣本檔案中指定觸發程式。

如需使用 excludebatch更複雜的觸發程式,您必須使用完整的語法,如下列範例所示。

# specific branch build
trigger:
  branches:
    include:
    - main
    - releases/*
    exclude:
    - releases/old*

在上述範例中,如果變更推送至 main 或任何發行分支,管線將會觸發。 不過,如果對以 開頭 old的 releases 分支進行變更,則不會觸發它。

如果您指定不含 exclude 子句的 include 子句,則它相當於在 include 子句中指定 *

除了在 branches 清單中指定分支名稱之外,您也可以使用下列格式,根據標記來設定觸發程式:

trigger:
  branches:
    include:
      - refs/tags/{tagname}
    exclude:
      - refs/tags/{othertagname}

如果您未指定任何觸發程式,且 未啟用 [停用隱含 YAML CI 觸發 程式] 設定,預設值會如同您撰寫的一樣:

trigger:
  branches:
    include:
    - '*'  # must quote since "*" is a YAML reserved character; we want a string

重要

當您指定觸發程式時,它會取代預設的隱含觸發程式,而且只會推送至明確設定為包含的分支會觸發管線。 先處理 Include,然後從該清單中移除排除。

批處理 CI 執行

如果您有許多小組成員經常上傳變更,您可能會想要減少您開始的執行次數。 如果您將 設定 batchtrue,當管線正在執行時,系統會等候執行完成,然後啟動另一個執行,並執行尚未建置的所有變更。

# specific branch build with batching
trigger:
  batch: true
  branches:
    include:
    - main

注意

batch 存放庫資源觸發程式不支援。

為了釐清此範例,讓我們假設Amain推送會導致上述管線執行。 當該管線正在執行時,會進行額外的推送 B ,並 C 發生在存放庫中。 這些更新不會立即啟動新的獨立執行。 但在第一次執行完成之後,所有推送都會一起批處理,並啟動新的執行。

注意

如果管線有多個作業和階段,則第一次執行仍應完成或略過其所有作業和階段,再啟動第二個執行之前,仍應達到終端狀態。 基於這個理由,您必須在具有多個階段或核准的管線中使用這項功能時小心。 如果您想要在這類情況下批處理組建,建議您將 CI/CD 程式分割成兩個管線,一個用於建置(含批處理),另一個用於部署。

路徑

您可以指定要包含或排除的檔案路徑。

# specific path build
trigger:
  branches:
    include:
    - main
    - releases/*
  paths:
    include:
    - docs
    exclude:
    - docs/README.md

當您指定路徑時,如果您使用 Azure DevOps Server 2019.1 或更低版本,則必須明確指定要觸發的分支。 您無法僅觸發路徑篩選的管線;您也必須有分支篩選,且符合路徑篩選條件的已變更檔案必須來自符合分支篩選的分支。 如果您使用 Azure DevOps Server 2020 或更新版本,您可以省略 branches 以篩選所有分支與路徑篩選條件。

路徑篩選支援通配符。 例如,您可以包含符合 src/app/**/myapp*的所有路徑。 您可以在指定路徑篩選時,使用通配符 (***?)

  • 路徑一律會指定相對於存放庫根目錄。
  • 如果您未設定路徑篩選,則預設會隱含包含存放庫的根資料夾。
  • 如果您排除路徑,除非您將路徑限定為更深入的資料夾,否則也無法包含該路徑。 例如,如果您排除 /tools,則可以包含 /tools/trigger-runs-on-these
  • 路徑篩選的順序並不重要。
  • Git 中的路徑會區分大小寫。 請務必使用與實際資料夾相同的案例。
  • 您無法在路徑中使用 變數 ,因為變數會在運行時間評估(觸發程式引發之後)。

標籤

除了在上一節所涵蓋的清單中指定標籤 branches 之外,您還可以直接指定要包含或排除的標籤:

# specific tag
trigger:
  tags:
    include:
    - v2.*
    exclude:
    - v2.0

如果您未指定任何標記觸發程式,則根據預設,標籤將不會觸發管線。

重要

如果您將標籤與分支篩選結合,則如果符合分支篩選條件或符合標籤篩選條件,觸發程式就會引發。 例如,如果推送的標籤符合分支篩選條件,即使標籤篩選排除標籤,管線也會觸發,因為推送符合分支篩選條件。

退出宣告 CI

停用 CI 觸發程式

您可以藉由指定 trigger: none來完全退出 CI 觸發程式。

# A pipeline with no CI trigger
trigger: none

重要

當您將變更推送至分支時,系統會評估該分支中的 YAML 檔案,以判斷是否應該啟動 CI 執行。

TFS 中無法使用YAML管線。

略過個別推送的 CI

您也可以告訴 Azure Pipelines 略過執行管線,推送通常會觸發。 只要包含在 ***NO_CI*** 屬於推送一部分的任何認可訊息中,Azure Pipelines 就會略過此推送的執行 CI。

您也可以告訴 Azure Pipelines 略過執行管線,推送通常會觸發。 只要包含在 [skip ci] 屬於推送一部分的任何認可訊息或描述中,Azure Pipelines 就會略過此推送的執行 CI。 您也可以使用下列任何變化。

  • [skip ci][ci skip]
  • skip-checks: trueskip-checks:true
  • [skip azurepipelines][azurepipelines skip]
  • [skip azpipelines][azpipelines skip]
  • [skip azp][azp skip]
  • ***NO_CI***

在條件中使用觸發程序類型

根據啟動執行的觸發程式類型而定,在您的管線中執行不同的步驟、作業或階段是常見的案例。 您可以使用系統變數 Build.Reason來執行此動作。 例如,將下列條件新增至您的步驟、作業或階段,以將其從PR驗證中排除。

condition: and(succeeded(), ne(variables['Build.Reason'], 'PullRequest'))

建立新分支時觸發程序的行為

設定相同存放庫的多個管線很常見。 例如,您可能有一個管線可建置應用程式的檔,而另一個管線可建置原始程式碼。 您可以在每個管線中設定具有適當分支篩選條件和路徑篩選條件的 CI 觸發程式。 例如,您可能會想要在將更新推送至資料夾時觸發一個管線,而當您將更新推送至 docs 應用程式程式代碼時,可能會觸發另一個管線。 在這些情況下,您必須瞭解建立新分支時如何觸發管線。

以下是當您將新的分支(符合分支篩選條件)推送至存放庫時的行為:

  • 如果您的管線具有路徑篩選,只有在新分支變更符合該路徑篩選條件的檔案時,才會觸發它。
  • 如果您的管線沒有路徑篩選,即使新分支中沒有任何變更,也會觸發它。

萬用字元

指定分支、標記或路徑時,您可以使用確切的名稱或通配符。 通配符模式允許 * 比對零或多個字元,以及 ? 比對單一字元。

  • 如果您在 YAML 管線中使用 來啟動模式 * ,則必須以引號括住模式,例如 "*-releases"
  • 針對分支和標記:
    • 通配符可能會在模式中的任何位置出現。
  • 針對路徑:
    • 在 Azure DevOps Server 2022 和更新版本中,包括 Azure DevOps Services,通配符可能會在路徑模式內的任何位置出現,而且您可以使用 *?
    • 在 Azure DevOps Server 2020 和更低版本中,您可能會包含 * 為最後一個字元,但不會自行指定目錄名稱以外的任何動作。 您可能 包含在 * 路徑篩選的中間,而且可能不會使用 ?
trigger:
  branches:
    include:
    - main
    - releases/*
    - feature/*
    exclude:
    - releases/old*
    - feature/*-working
  paths:
    include:
    - docs/*.md

PR 觸發程式

每當開啟提取要求或推送變更時,提取要求 (PR) 觸發程式會導致管線執行。 在 Azure Repos Git 中,此功能是使用分支原則來實作。 若要啟用PR驗證,請流覽至所需分支的分支原則,並設定該分支的 建置驗證原則 。 如需詳細資訊,請參閱 設定分支原則

如果您有開啟的 PR,並將變更推送至其來源分支,可能會執行多個管線:

  • 目標分支的組建驗證原則所指定的管線將會在合併認可執行(提取要求的來源和目標分支之間的合併程序代碼),不論是否有訊息或描述包含[skip ci]的推送認可(或其任何變體)。
  • 如果 沒有任何 訊息或描述包含 [skip ci] 其訊息或描述的推送認可,則由PR來源分支變更所觸發的管線(或其任何變體)。 如果至少有一個推送認可包含 [skip ci],管線將不會執行。

最後,合併PR之後,Azure Pipelines 會執行由推送至目標分支所觸發的 CI 管線,即使某些合併的認可訊息或描述包含 [skip ci] (或其任何變體)。

注意

若要設定 Azure Repos Git 存放庫的驗證組建,您必須是其專案的專案管理員。

注意

即使您設定分支原則,草稿提取要求 也不會觸發管線。

驗證分叉的貢獻

從 Azure Repos 分支建置提取要求與在相同存放庫或專案中建置提取要求並無不同。 您只能在項目所屬的相同組織中建立分叉。

限制作業授權範圍

Azure Pipelines 提供數個安全性設定,以設定管線執行的作業授權範圍。

將作業授權範圍限制為目前專案

Azure Pipelines 提供兩 個限制作業授權範圍至目前的項目 設定:

  • 將作業授權範圍限制為非發行管線的目前專案 - 此設定適用於 YAML 管線 和傳統組建管線。 此設定不適用於傳統發行管線。
  • 將作業授權範圍限制為發行管線 目前的專案 - 此設定 僅適用於傳統發行管線

除非已啟用管線類型的相關設定,否則管線會使用集合範圍存取令牌執行。 [ 限制作業授權範圍 ] 設定可讓您減少所有管線對目前專案的存取範圍。 如果您要存取組織中不同專案中的 Azure Repos Git 存放庫,這可能會影響您的管線。

如果您的 Azure Repos Git 存放庫位於與管線不同的專案中,且 已啟用管線類型的 [限制作業授權範圍 ] 設定,您必須將管線建置服務識別的許可權授與第二個專案。 如需詳細資訊,請參閱 管理組建服務帳戶許可權

Azure Pipelines 提供安全性設定,以設定管線執行作業授權範圍。

  • 將作業授權範圍限制為目前的專案 - 此設定適用於 YAML 管線和傳統組建管線。 此設定不適用於 傳統發行管線

除非啟用將作業授權範圍限製為目前專案,否則管線會使用集合範圍存取令牌執行。 此設定可讓您減少所有管線目前專案的存取範圍。 如果您要存取組織中不同專案中的 Azure Repos Git 存放庫,這可能會影響您的管線。

如果您的 Azure Repos Git 存放庫位於與管線不同的專案中,且 已啟用 [限制作業授權範圍 ] 設定,您必須將管線建置服務識別的許可權授與至第二個專案。 如需詳細資訊,請參閱作業授權範圍

如需限制作業授權範圍的詳細資訊,請參閱瞭解作業存取令牌

將作業授權範圍限制為參考的 Azure DevOps 存放庫

管線可以存取授權專案中的任何 Azure DevOps 存放庫,如先前 將作業授權範圍限制為目前專案 一節所述,除非 已啟用將作業授權範圍限制為參考的 Azure DevOps 存放庫 。 啟用此選項后,您可以將所有管線的存取範圍縮減為只有使用該存放庫之管線作業中的步驟或uses語句明確參考checkout的 Azure DevOps 存放庫。

若要設定此設定,請流覽至 [組織設定] 或 [專案] 設定 設定管線。 如果在組織層級啟用,設定會呈現灰色,且項目設定層級無法使用。

啟用對參考 Azure DevOps 存放庫的作業授權範圍時,您的 YAML 管線必須明確參考您想要在管線中使用的任何 Azure Repos Git 存放庫,做為使用存放庫之作業的簽出步驟。 除非第一次明確參考該存放庫,否則您無法使用 Azure Repos Git 存放庫的腳本工作和 Git 命令來擷取程式代碼。

當您啟用 Azure DevOps 存放庫的作業授權範圍限制時 ,在管線中使用 Azure Repos Git 存放庫之前,您不需要明確參考 Azure Repos Git 存放庫 有幾個例外狀況。

  • 如果您的管線中沒有明確的簽出步驟,就好像您有步驟 checkout: self 一樣,而且已取出存放 self 庫。
  • 如果您使用腳本在公用專案中的存放庫上執行只讀作業,則不需要在步驟中 checkout 參考公用專案存放庫。
  • 如果您使用腳本向存放庫提供自己的驗證,例如 PAT,則不需要在步驟中 checkout 參考該存放庫。

例如,當啟用將作業授權範圍限制為參考的 Azure DevOps 存放庫時,如果您的管線位於FabrikamProject/Fabrikam您組織中的存放庫,而且您想要使用腳本來簽出FabrikamProject/FabrikamTools存放庫時,您必須在步驟或uses語句中checkout參考此存放庫。

如果您已經在管線中使用簽出步驟簽出 FabrikamTools 存放庫,您後續可能會使用腳本與該存放庫互動。

steps:
- checkout: git://FabrikamFiber/FabrikamTools # Azure Repos Git repository in the same organization
- script: # Do something with that repo

# Or you can reference it with a uses statement in the job
uses:
  repositories: # List of referenced repositories
  - FabrikamTools # Repository reference to FabrikamTools

steps:
- script: # Do something with that repo like clone it

注意

在許多案例中,可以利用多存放庫簽出,而不需要使用腳本來簽出管線中的其他存放庫。 如需詳細資訊,請參閱 查看管線中的多個存放庫。

保護 YAML 管線中存放庫的存取

管線可以存取授權專案中的任何 Azure DevOps 存放庫,如先前 限制作業授權範圍至目前專案 一節所述,除非 已啟用保護 YAML 管線中存放庫的 存取權。 啟用此選項后,您可以將所有管線的存取範圍縮減為只有使用該存放庫之管線作業中的步驟或uses語句明確參考checkout的 Azure DevOps 存放庫。

若要設定此設定,請流覽至 [組織設定] 或 [專案] 設定 設定管線。 如果在組織層級啟用,設定會呈現灰色,且項目設定層級無法使用。

重要

默認會針對在 2020 年 5 月之後建立的新組織和專案,啟用 YAML 管線 中存放庫的存取。 啟用保護 YAML 管線中存放庫的存取權時,您的 YAML 管線必須明確參考您想要在管線中使用的任何 Azure Repos Git 存放庫,做為使用存放庫之作業中的簽出步驟。 除非第一次明確參考該存放庫,否則您無法使用 Azure Repos Git 存放庫的腳本工作和 Git 命令來擷取程式代碼。

在啟用 YAML 管線中存放庫的存取權時,您不需要在管線中使用 Azure Repos Git 存放庫之前,有幾個例外狀況。

  • 如果您的管線中沒有明確的簽出步驟,就好像您有步驟 checkout: self 一樣,而且已取出存放 self 庫。
  • 如果您使用腳本在公用專案中的存放庫上執行只讀作業,則不需要在步驟中 checkout 參考公用專案存放庫。
  • 如果您使用腳本向存放庫提供自己的驗證,例如 PAT,則不需要在步驟中 checkout 參考該存放庫。

例如,當啟用 [保護 YAML 管線中存放庫的存取權] 時,如果您的管線位於FabrikamProject/Fabrikam您組織中的存放庫,而且您想要使用腳本來簽出FabrikamProject/FabrikamTools存放庫,您必須在步驟或uses語句中checkout參考此存放庫。

如果您已經在管線中使用簽出步驟簽出 FabrikamTools 存放庫,您後續可能會使用腳本與該存放庫互動。

steps:
- checkout: git://FabrikamFiber/FabrikamTools # Azure Repos Git repository in the same organization
- script: # Do something with that repo
# Or you can reference it with a uses statement in the job
uses:
  repositories: # List of referenced repositories
  - FabrikamTools # Repository reference to FabrikamTools
steps:
- script: # Do something with that repo like clone it

注意

在許多案例中,可以利用多存放庫簽出,而不需要使用腳本來簽出管線中的其他存放庫。 如需詳細資訊,請參閱 查看管線中的多個存放庫。

結帳

觸發管線時,Azure Pipelines 會從 Azure Repos Git 存放庫提取您的原始程式碼。 您可以控制這種情況發生方式的各種層面。

注意

當您在管線中包含結帳步驟時,我們會執行下列命令: git -c fetch --force --tags --prune --prune-tags --progress --no-recurse-submodules origin --depth=1。 如果這不符合您的需求,您可以選擇排除內建結帳, checkout: none 然後使用腳本工作來執行您自己的結帳。

Git 的慣用版本

Windows 代理程序隨附自己的 Git 複本。 如果您要提供自己的 Git,而不是使用包含的複本,請將 設定 System.PreferGitFromPathtrue。 非 Windows 代理程式上此設定一律為 true。

簽出路徑

如果您簽出單一存放庫,根據預設,您的原始程式碼會簽入名為 s的目錄。 針對 YAML 管線,您可以使用 來checkoutpath變更此專案。 指定路徑相對於 $(Agent.BuildDirectory)。 例如:如果簽出路徑值為 ,且 $(Agent.BuildDirectory)mycustompathC:\agent\_work\1,則原始程式碼會簽入 C:\agent\_work\1\mycustompath

如果您使用多個步驟並簽出多個 checkout 存放庫,且未使用 明確指定資料夾 path,則每個存放庫都會放在以存放庫命名的 s 子資料夾中。 例如,如果您取出名為 和code的兩個tools存放庫,原始程式碼將會簽入 C:\agent\_work\1\s\toolsC:\agent\_work\1\s\code

請注意,簽出路徑值無法設定為上層以上$(Agent.BuildDirectory)的任何目錄層級,因此path\..\anotherpath會產生有效的簽出路徑(亦即),但類似 ..\invalidpath 的值不會(C:\agent\_work\1\anotherpath亦即 C:\agent\_work\invalidpath)。

您可以在 path 管線的 [簽出 ] 步驟中設定設定。

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

子模組

如果您想要從子模組下載檔,您可以在submodules管線的 [簽出] 步驟中設定設定。

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

只要您的 Git 子模組為下列專案,組建管線就會取出您的 Git 子模組:

  • 未經驗證: 公用、未經驗證的存放庫,不需要任何認證即可複製或擷取。

  • 認證:

    • 包含在與上面指定的 Azure Repos Git 存放庫相同的專案中。 代理程式用來從主要存放庫取得來源的相同認證也會用來取得子模組的來源。

    • 使用相對於主要存放庫的網址來新增 。 例如:

      • 這會取出: git submodule add ../../../FabrikamFiberProject/_git/FabrikamFiber FabrikamFiber

        在此範例中,子模組是指相同 Azure DevOps 組織中的存放庫 (FabrikamFiber),但在不同的專案中(FabrikamFiberProject)。 代理程式用來從主要存放庫取得來源的相同認證也會用來取得子模組的來源。 這需要作業存取令牌能夠存取第二個專案中的存放庫。 如果您限制作業存取令牌,如上一節所述,您將無法執行此動作。 您可以允許作業存取令牌存取第二個專案中的存放庫,方法是明確授與第二個專案中專案建置服務帳戶的存取權,或使用集合範圍的存取令牌,而不是整個組織的專案範圍令牌。 如需這些選項及其安全性含意的詳細資訊,請參閱 存取存放庫、成品和其他資源

      • 此檔案不會取出: git submodule add https://fabrikam-fiber@dev.azure.com/fabrikam-fiber/FabrikamFiberProject/_git/FabrikamFiber FabrikamFiber

使用 Checkout 子模組選項的替代方案

在某些情況下,您無法使用 [結帳] 子模組 選項。 您可能有需要一組不同認證才能存取子模組的案例。 例如,如果您的主要存放庫和子模組存放庫未儲存在相同的 Azure DevOps 組織中,或您的作業存取令牌無法存取不同專案中的存放庫,就可能發生此情況。

如果您無法使用 Checkout 子模組 選項,則可以改用自定義腳本步驟來擷取子模組。 首先,取得個人存取令牌 (PAT),並以 作為前置詞 pat:。 接下來, 以base64編碼 此前置字串來建立基本驗證令牌。 最後,將此腳本新增至您的管線:

git -c http.https://<url of submodule repository>.extraheader="AUTHORIZATION: Basic <BASE64_ENCODED_STRING>" submodule update --init --recursive

請務必將 「<BASE64_ENCODED_STRING>」 取代為您的Base64編碼 「pat:token」 字串。

在您的專案或建置管線中使用秘密變數來儲存您產生的基本驗證令牌。 使用該變數在上述 Git 命令中填入秘密。

注意

問:為什麼無法在代理程式上使用 Git 認證管理員?答: 將子模組認證儲存在安裝在私人組建代理程式的 Git 認證管理員中通常無效,因為認證管理員可能會在更新子模組時提示您重新輸入認證。 當使用者互動無法進行時,在自動化組建期間不想要這樣做。

同步標記

重要

Azure Repos Git 支援同步標籤功能與 Azure DevOps Server 2022.1 和更新版本。

簽出步驟會在擷取 Git 存放庫的內容時使用 --tags 選項。 這會導致伺服器擷取所有標記,以及這些標記所指向的所有物件。 這會增加在管線中執行工作的時間,特別是如果您有一些標記的大型存放庫。 此外,即使啟用淺層擷取選項,簽出步驟也會同步處理標記,因而可能會破壞其目的。 為了減少從 Git 存放庫擷取或提取的數據量,Microsoft 已新增簽出選項來控制同步標記的行為。 此選項可在傳統和 YAML 管線中使用。

簽出存放庫時,是否可以藉由設定 fetchTags 屬性,以及在UI 中設定同步標記設定來設定存放庫時同步處理標籤

您可以在 fetchTags 管線的 [簽出 ] 步驟中設定設定。

若要在 YAML 中設定設定,請設定 fetchTags 屬性。

steps:
- checkout: self
  fetchTags: true

您也可以使用管線設定 UI 中的 [ 同步標記 ] 選項來設定此設定。

  1. 編輯您的 YAML 管線,然後選擇 [ 更多動作]、 [觸發程式]。

    Screenshot of more triggers menu.

  2. 選擇 [YAML]、 [取得來源]。

    Screenshot of Get sources.

  3. 設定同步 標記 設定。

    Screenshot of Sync tags setting.

注意

如果您明確在步驟中checkout設定fetchTags,該設定會優先於管線設定UI中設定的設定。

預設行為

  • 對於在 2022 年 9 月發行的 Azure DevOps 短期衝刺 209 發行之前建立的現有管線,同步標記的預設值會與新增同步標記選項之前的現有行為相同,也就是 true
  • 針對在 Azure DevOps 短期衝刺版本 209 之後建立的新管線,同步標記的預設值為 false

注意

如果您明確在步驟中checkout設定fetchTags,該設定會優先於管線設定UI中設定的設定。

淺層

您可能想要限制歷程記錄中要下載多少遠。 實際上,這會導致 git fetch --depth=n。 如果您的存放庫很大,此選項可能會讓您的組建管線更有效率。 如果您的存放庫已在使用中很長一段時間且具有可調整歷程記錄,您的存放庫可能會很大。 如果您新增和稍後刪除的大型檔案,也可能很大。

重要

在 2022 年 9 月 Azure DevOps 短期衝刺 209 更新之後建立的新管線預設會啟用淺層擷取,並設定深度為 1。 先前的預設值不是淺層擷取。 若要檢查您的管線,請檢視 管線設定 UI 中的淺層擷取 設定,如下一節所述。

您可以在 fetchDepth 管線的 [簽出 ] 步驟中設定設定。

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

您也可以在管線設定UI中設定 淺層深度選項,以設定提取深度

  1. 編輯您的 YAML 管線,然後選擇 [ 更多動作]、 [觸發程式]。

    Screenshot of more triggers menu.

  2. 選擇 [YAML]、 [取得來源]。

    Screenshot of Get sources.

  3. 設定淺層擷 設定。 取消核取 淺層擷取以停用淺層擷取 ,或核取方塊並輸入 深度 以啟用淺層擷取。

    Screenshot of options.

注意

如果您明確在步驟中checkout設定fetchDepth,該設定會優先於管線設定UI中設定的設定。 設定 fetchDepth: 0 會擷取所有歷程記錄並覆寫淺層擷 設定。

在這些情況下,此選項可協助您節省網路和記憶體資源。 它也可能會節省時間。 它不一定會節省時間的原因是,在某些情況下,伺服器可能需要花費時間計算認可,以下載您所指定的深度。

注意

當管線啟動時,要建置的分支會解析為認可標識符。 然後,代理程式會擷取分支,並簽出所需的認可。 當分支解析為認可標識碼,以及代理程式執行簽出時,有一個小視窗。 如果分支快速更新,而且您為淺層擷取設定了非常小的值,當代理程式嘗試取出時,認可可能不存在。如果發生這種情況,請增加淺層擷取深度設定。

不要同步來源

您可能想要略過擷取新的認可。 當您想要下列情況時,此選項很有用:

  • 使用您自己的自定義選項來 Git init、設定和擷取。

  • 使用建置管線來執行自動化(例如某些腳本),這些腳本不相依於版本控制中的程序代碼。

您可以藉由設定 ,在管線的 [簽出] 步驟中設定 [不要同步處理來源] 設定checkout: none

steps:
- checkout: none  # Don't sync sources

注意

當您使用此選項時,代理程式也會略過執行 Git 命令來清除存放庫。

清除組建

您可以在組建執行之前,執行不同形式的清除自我裝載代理程式的工作目錄。

一般而言,為了加快自我裝載代理程式的效能,請勿清除存放庫。 在此情況下,若要獲得最佳效能,請確定您也會藉由停用您用來建置之工作或工具的任何 Clean 選項,以累加建置。

如果您需要清除存放庫(例如避免先前組建中剩餘檔案所造成的問題),您的選項如下。

注意

如果您使用 Microsoft 裝載的代理程式 ,則清除無效,因為您每次都會收到新的代理程式。

您可以在 clean 管線的 [簽出 ] 步驟中設定設定。

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

clean 設定為 true 建置管線時,會在 中 $(Build.SourcesDirectory)執行任何變更的復原。 更具體地說,在擷取來源之前,會執行下列 Git 命令。

git clean -ffdx
git reset --hard HEAD

如需更多選項,您可以設定workspace作業設定。

jobs:
- job: string  # name of the job, A-Z, a-z, 0-9, and underscore
  ...
  workspace:
    clean: outputs | resources | all # what to clean up before the job runs

這會提供下列全新選項。

  • outputs:與上一個簽出工作中所述的清除設定相同的作業,以及:刪除並重新建立 $(Build.BinariesDirectory)。 請注意, $(Build.ArtifactStagingDirectory) 不論這些設定為何,在每次建置之前一律會刪除和重新建立 和 $(Common.TestResultsDirectory)

  • resources:刪除並重新建立 $(Build.SourcesDirectory)。 這會導致初始化每個組建的新本機 Git 存放庫。

  • all:刪除並重新建立 $(Agent.BuildDirectory)。 這會導致初始化每個組建的新本機 Git 存放庫。

標籤來源

您可能想要為原始程式碼檔案加上標籤,讓您的小組能夠輕鬆地識別已完成組建中包含的每個檔案版本。 您也可以選擇指定原始程式碼是否應該針對所有組建加上標籤,還是只針對成功的組建加上標籤。

您目前無法在 YAML 中設定此設定,但可以在傳統編輯器中設定。 編輯 YAML 管線時,您可以從 YAML 編輯器選單選擇任一 觸發程式 ,以存取傳統編輯器。

Configure Git options, YAML.

從傳統編輯器中,依序選擇 [YAML]、[ 取得來源 ] 工作,然後在該處設定所需的屬性。

From the Classic editor, choose YAML > Get sources.

在 Tag 格式,您可以使用具有 「全部」範圍的使用者定義和預先定義變數。例如:

$(Build.DefinitionName)_$(Build.DefinitionVersion)_$(Build.BuildId)_$(Build.BuildNumber)_$(My.Variable)

前四個變數是預先定義的。 My.Variable您可以在 [變數] 索引標籤定義。

組建管線會使用 Git 標籤為您的來源加上 標籤

某些組建變數可能會產生不是有效標籤的值。 例如,和 $(Build.DefinitionName) 之類的$(Build.RequestedFor)變數可以包含空格符。 如果值包含空格符,則不會建立標記。

建置管線標記來源之後,Git ref refs/tags/{tag} 的成品會自動新增至完成的組建。 這可讓您的小組提供額外的可追蹤性和更方便使用的方式,從組建巡覽至所建置的程序代碼。 卷標會被視為組建成品,因為它是由組建所產生。 手動或透過保留原則刪除組建時,也會刪除標記。

常見問題集

與 Azure Repos 整合相關的問題分為三個類別:

  • 失敗的觸發程式 當我將更新推送至存放庫時,我的管線不會觸發。
  • 簽出失敗:正在觸發我的管線,但在簽出步驟中失敗。
  • 錯誤版本 我的管線執行,但它使用非預期的來源/YAML 版本。

失敗的觸發程式

我剛使用 CI/PR 觸發程式建立新的 YAML 管線,但不會觸發管線。

請遵循下列步驟來針對失敗的觸發程式進行疑難解答:

  • 您的 YAML CI 或 PR 觸發 程式是否由 UI 中的管線設定覆寫? 編輯管線時,請選擇 ...,然後選擇 [觸發程式]。

    Pipeline settings UI.

    請從此處檢查 [覆寫 YAML 觸發程式] 設定,以取得存放庫可用的觸發程式類型(持續整合提取要求驗證)。

    Override YAML trigger from here.

  • 您是否在 YAML 檔案或存放庫的分支原則中設定 PR 觸發程式? 對於 Azure Repos Git 存放庫,您無法在 YAML 檔案中設定 PR 觸發程式。 您必須使用 分支原則
  • 管線已暫停或停用嗎? 開啟管線的編輯器,然後選取要檢查 設定。 如果您的管線已暫停或停用,則觸發程式無法運作。

  • 您是否已在正確的分支中更新 YAML 檔案? 如果您將更新推送至分支,則相同分支中的 YAML 檔案會控管 CI 行為。 如果您將更新推送至來源分支,則合併來源分支與目標分支所產生的 YAML 檔案會控管 PR 行為。 請確定正確分支中的 YAML 檔案具有必要的 CI 或 PR 組態。

  • 您是否已正確設定觸發程式? 當您定義 YAML 觸發程式時,您可以同時指定分支、標記和路徑的 include 和 exclude 子句。 請確定 include 子句符合認可的詳細數據,而且 exclude 子句不會排除這些子句。 檢查觸發程式的語法,並確定其正確無誤。

  • 您是否在定義觸發程式或路徑時使用變數? 不支援。

  • 您是否使用 YAML 檔案的樣本? 如果是,請確定您的觸發程式定義於主要 YAML 檔案中。 不支援範本檔案內定義的觸發程式。

  • 您是否已排除您推送變更的分支或路徑? 將變更推送至內含分支中的包含路徑,以進行測試。 請注意,觸發程式中的路徑會區分大小寫。 在指定觸發程式中的路徑時,請務必使用與實際資料夾相同的案例。

  • 您剛推送新分支嗎? 如果是,新分支可能不會啟動新的執行。 請參閱一節。

我的 CI 或 PR 觸發程式正常運作。 但是,他們現在停止工作了。

請先完成上一個問題中的疑難解答步驟。 然後,請遵循下列其他步驟:

  • 您的PR中有合併衝突嗎? 若為未觸發管線的PR,請開啟它並檢查是否有合併衝突。 解決合併衝突。

  • 您遇到推送或 PR 事件的處理延遲嗎? 您通常可查看問題是否專屬於單一管線,或是您專案中所有管線或存放庫通用,來確認此問題。 如果任何存放庫的推送或PR更新都表現出此徵兆,我們可能會遇到處理更新事件的延遲。 檢查我們狀態頁面上是否有服務中斷。 如果狀態頁面顯示問題,則我們的小組必須已經開始處理。 請經常檢查頁面,以取得問題的更新。

我不希望使用者在更新 YAML 檔案時覆寫觸發程式的分支清單。 如何執行此作業?

具有參與程式代碼許可權的使用者可以更新 YAML 檔案,並包含/排除其他分支。 因此,用戶可以在 YAML 檔案中包含自己的功能或使用者分支,並將該更新推送至功能或使用者分支。 這可能會導致該分支的所有更新觸發管線。 如果您想要防止此行為,您可以:

  1. 在 Azure Pipelines UI 中編輯管線。
  2. 瀏覽至 [ 觸發程式] 選單。
  3. 從這裡選取 [覆寫 YAML 持續整合觸發程式]。
  4. 指定要包含或排除觸發程式的分支。

當您遵循這些步驟時,會忽略 YAML 檔案中指定的任何 CI 觸發程式。

我在 YAML 管線中有多個存放庫。 我該如何為每個存放庫設定觸發程序?

請參閱使用多個存放庫中的觸發程序。

簽出失敗

我在簽出步驟期間在記錄檔中看到下列錯誤。 如何修正?

remote: TF401019: The Git repository with name or identifier XYZ does not exist or you do not have permissions for the operation you are attempting.
fatal: repository 'XYZ' not found
##[error] Git fetch failed with exit code: 128

請遵循下列步驟,針對您的簽出失敗進行疑難解答:

  • 存放庫仍然存在嗎? 首先,請務必在 Repos 頁面中開啟它

  • 您是否使用文稿存取存放庫? 如果是,請檢查 [ 將作業授權範圍限制為參考的 Azure DevOps 存放庫 ] 設定。 啟用對參考 Azure DevOps 存放庫的作業授權範圍時,除非在管線中先明確參考 Azure Repos Git 存放庫,否則您將無法使用腳本簽出 Azure Repos Git 存放庫。

  • 管線的作業授權範圍為何

    • 如果範圍是 集合

      • 這可能是間歇性錯誤。 重新執行管線。
      • 有人可能已移除專案集合建置服務帳戶存取權。
        • 移至 存放庫所在專案的 [項目設定 ]。 選取 [存放庫>存放庫特定存放庫>],然後選取 [安全性]。
        • 檢查專案集合組建服務 (your-collection-name) 是否存在於使用者清單中。
        • 檢查該帳戶 是否有 [建立] 卷標[讀取] 存取權。
    • 如果範圍是 專案

      • 存放庫是否與管線位於相同的專案中?
        • 是:
          • 這可能是間歇性錯誤。 重新執行管線。
          • 有人可能已移除專案建置服務帳戶存取權。
            • 移至 存放庫所在專案的 [項目設定 ]。 選取 [存放庫>存放庫特定存放庫>],然後選取 [安全性]。
            • 檢查 your-project-name Build Service (your-collection-name) 是否存在於使用者清單中。
            • 檢查該帳戶 是否有 [建立] 卷標[讀取] 存取權。
        • 否:
          • 您的管線是否在公用專案中?

錯誤的版本

管線中使用了錯誤的 YAML 檔案版本。 這是為什麼?

  • 針對 CI 觸發程式,系統會評估您要推送之分支中的 YAML 檔案,以查看是否應該執行 CI 組建。
  • 針對PR觸發程式,會評估合併PR來源和目標分支所產生的YAML檔案,以查看是否應該執行PR組建。