建置 Azure Repos Git 或 TFS Git 存放庫

文章
04/04/2024

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

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

選擇要建置的存放庫

YAML
傳統

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

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

建立管線時，若要選擇要建置的存放庫，請先選取存放庫所屬的專案。然後，選取存放庫。

若要在管線中複製其他存放庫：

如果存放庫位於與管線相同的專案中，或存取令牌（如下所述）可以存取不同專案中的存放庫，請使用下列命令：

git clone -c http.extraheader="AUTHORIZATION: bearer $(System.AccessToken)" <clone URL>

若要在 System.AccessToken 腳本中使用，您必須先讓它可供腳本使用。若要這樣做，請選取編輯器中 [工作] 索引標籤底下的作業，在右側面板中選取 [其他選項]，然後核取 [允許腳本存取 OAuth 令牌] 選項。
如果存取權杖（如下所述）沒有存放庫的存取權：
1. 取得具有Code (read)範圍的個人存取令牌（PAT），並在前面加上PAT:
2. Base64 編碼此字串以建立基本驗證令牌。
3. 使用下列命令在管線中新增腳本，以複製該存放庫 git clone -c http.extraheader="AUTHORIZATION: basic <BASIC_AUTH_TOKEN>" <clone URL>

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

CI 觸發程式

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

YAML
傳統

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 檔案中指定觸發程式。您無法在樣本檔案中指定觸發程式。

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

# 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 執行

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

# 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 中的路徑會區分大小寫。請務必使用與實際資料夾相同的案例。
您無法在路徑中使用變數，因為變數會在運行時間評估（觸發程式引發之後）。

退出宣告 CI

停用 CI 觸發程式

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

# A pipeline with no CI trigger
trigger: none

重要

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

如果您想要每當有人簽入程式代碼時執行組建，請在 [觸發程式] 索引卷標上選取 [啟用持續整合]，以啟用此觸發程式。

批次變更

如果您有許多小組成員經常上傳變更，而且您想要減少您正在執行的組建數目，請選取此複選框。如果您選取此選項，當組建執行時，系統會等候執行完成，然後將尚未建置之所有變更的另一個執行排入佇列。

您可以批處理變更，並將它們一起建置。

注意

如果您使用批處理搭配多階段 YAML 管線，則執行必須到達終端機狀態，才能啟動下一個管線。這通常不理想，因為多階段管線可能會經歷核准和長時間執行的部署階段。在這些情況下，建議您遵循下列其中一個解決方案：

請勿使用批處理
將管線分割成兩個不同的管線 - 一個用於 CI 和一個 CD
在階段設定適當的條件以略過它們，並快速終止執行

分支篩選

您可以指定您要觸發組建的分支。如果您想要使用通配符，請輸入分支規格（例如 features/modules/*），然後按 Enter。

路徑篩選

如果您的 Git 存放庫位於 Azure Repos 或 TFS 中，您也可以指定路徑篩選條件，以減少您想要觸發組建的檔案集。

提示：

路徑一律會指定相對於存放庫根目錄。

如果您未設定路徑篩選，則預設會隱含包含存放庫的根資料夾。

如果您排除路徑，除非您將路徑限定為更深入的資料夾，否則也無法包含該路徑。例如，如果您排除 /tools，則可以包含 /tools/trigger-runs-on-these

路徑篩選的順序並不重要。

Git 中的路徑會區分大小寫。請務必使用與實際資料夾相同的案例。

範例

例如，您想要讓組建由功能分支中的 main 變更觸發，但不是全部變更。您也不希望工具資料夾中檔案的變更觸發組建。

設定持續整合觸發程式分支篩選。

略過個別推送的 CI

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

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

[skip ci] 或 [ci skip]
skip-checks: true 或 skip-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 提供數個安全性設定，以設定管線執行的作業授權範圍。

將作業授權範圍限制為目前專案
保護 YAML 管線中存放庫的存取

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

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.PreferGitFromPath 為 true。非 Windows 代理程式上此設定一律為 true。

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

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

子模組

YAML
傳統

如果您想要從子模組下載檔，您可以在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 中設定同步標記設定來設定存放庫時同步處理標籤 。

YAML
傳統

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

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

steps:
- checkout: self
  fetchTags: true

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

編輯您的 YAML 管線，然後選擇 [ 更多動作]、 [觸發程式]。
選擇 [YAML]、 [取得來源]。
設定同步標記設定。

注意

如果您明確在步驟中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 中的淺層擷取 設定，如下一節所述。

YAML
傳統

您可以在 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中設定 淺層深度選項，以設定提取深度 。

編輯您的 YAML 管線，然後選擇 [ 更多動作]、 [觸發程式]。
選擇 [YAML]、 [取得來源]。
設定淺層擷取設定。取消核取 淺層擷取以停用淺層擷取 ，或核取方塊並輸入深度以啟用淺層擷取。

注意

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

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

注意

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

不要同步來源

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

使用您自己的自定義選項來 Git init、設定和擷取。
使用建置管線來執行自動化（例如某些腳本），這些腳本不相依於版本控制中的程序代碼。

YAML
傳統

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

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

注意

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

清除組建

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

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

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

注意

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

YAML
傳統

您可以在 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 存放庫。

從管線中 [取得來源] 工作的屬性選取 [清除] 設定，然後選取下列其中一個選項。

選取 [清除] 設定。

來源：建置管線會執行中$(Build.SourcesDirectory)任何變更的復原。更具體地說，在擷取來源之前，會執行下列 Git 命令。
```
git clean -ffdx
git reset --hard HEAD
```
來源和輸出目錄：與 上述 [來源 ] 選項相同的作業，以及：刪除並重新建立 $(Build.BinariesDirectory)。請注意， $(Build.ArtifactStagingDirectory) 不論這些設定為何，在每次建置之前一律會刪除和重新建立和 $(Common.TestResultsDirectory) 。
來源目錄：刪除並重新建立 $(Build.SourcesDirectory)。這會導致初始化每個組建的新本機 Git 存放庫。
所有建置目錄：刪除並重新建立 $(Agent.BuildDirectory)。這會導致初始化每個組建的新本機 Git 存放庫。

標籤來源

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

YAML
傳統

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

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

從 [傳統編輯器] 中選擇 [YAML > 取得來源]。

在 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 中的管線設定覆寫？編輯管線時，請選擇 ...，然後選擇 [觸發程式]。

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

您是否在 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 檔案中包含自己的功能或使用者分支，並將該更新推送至功能或使用者分支。這可能會導致該分支的所有更新觸發管線。如果您想要防止此行為，您可以：

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

當您遵循這些步驟時，會忽略 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組建。

分享方式：