Git 存放庫的管線選項

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

在 Azure DevOps 專案、GitHub、GitHub Enterprise Server、Bitbucket Cloud 或其他 Git 存放庫中編輯使用 Git 存放庫的管線時，您有下列選項。

功能	Azure Pipelines	Azure DevOps Server 2019 和更新版本	TFS 2018
分行	Yes	.是	Yes
Clean	Yes	.是	Yes
標籤或標籤來源	專案;僅限傳統	Team 專案	Team 專案
報表組建狀態	Yes	.是	Yes
查看子模組	Yes	.是	Yes
從 LFS 取出檔案	Yes	.是	Yes
複製第二個存放庫	Yes	.是	Yes
不要同步來源	Yes	.是	Yes
淺層	Yes	.是	是

注意

按兩下 [取得來源] 工作中的 [進階設定]，以查看上述一些選項。

分行

這是當您手動將此組建排入佇列時，想要成為預設值的分支。 如果您設定組建的排程觸發程式，這是組建會從中取得最新來源的分支。 當建置透過持續整合觸發時，預設分支沒有任何影響。 您通常會將此設定為與存放庫的預設分支相同（例如，「master」）。

清除代理程式上的本機存放庫

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

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

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

注意

如果您使用 Microsoft 裝載的代理程式 ，則清除無效，因為您每次都會收到新的代理程式。 使用自我裝載代理程式時，視代理程式集區的設定方式而定，您可能會取得後續管線執行的新代理程式（或相同管線中的階段或作業），因此 不 保證後續執行、作業或階段將能夠存取先前執行、作業或階段的輸出。

YAML

Azure Pipelines、Azure DevOps Server 2019 和更新版本

YAML 管線有數個不同的清除選項可供使用。

• 步驟 checkout 有選項 clean 。 當設定為 true時，管線會在擷取存放庫之前執行 execute git clean -ffdx && git reset --hard HEAD 。 如需詳細資訊，請參閱 簽出。
• 的workspacejob設定具有多個全新選項（輸出、資源、全部）。 如需詳細資訊，請參閱 工作區。
• 管線設定 UI 具有 [清除] 設定，當設定為 true 時，相當於為checkout管線中的每個步驟指定 clean: true 。 若要設定 [ 清除] 設定：

  1. 編輯您的管線，選擇 ...，然後選取 [ 觸發程式]。

     

  2. 選取 [YAML]、 [取得來源]，然後設定您想要的 [清除 ] 設定。 預設值為 True。

     

若要在手動執行管線時覆寫清除設定，您可以使用 運行時間參數。 在下列範例中，會使用運行時間參數來設定結帳清除設定。

parameters:
- name: clean
  displayName: Checkout clean
  type: boolean
  default: true
  values:
  - false
  - true

trigger:
- main

pool: FabrikamPool
#  vmImage: 'ubuntu-latest'

steps:
- checkout: self
  clean: ${{ parameters.clean }}

根據預設， clean 會設定為 ， true 但可在手動執行管線時覆寫，方法是取消核 取運行時間參數新增的 [簽出清除] 複選框。

傳統

Azure Pipelines、TFS 2018、TFS 2017.2、TFS 2017.3

選取下列其中一個選項：

• 來源：建置管線會執行 中$(Build.SourcesDirectory)任何變更的復原。 更具體地說，在擷取來源之前，會執行下列 Git 命令。

  git clean -ffdx
  git reset --hard HEAD
  

• 來源和輸出目錄：與 上述 [來源 ] 選項相同的作業，以及：刪除並重新建立 $(Build.BinariesDirectory)。 請注意， $(Build.ArtifactStagingDirectory) 不論這些設定為何，在每次建置之前一律會刪除和重新建立 和 $(Common.TestResultsDirectory) 。

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

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

標籤來源

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

注意

只有當組建中的來源存放庫是 GitHub 存放庫，或來自專案的 Git 或 TFVC 存放庫時，您才能使用此功能。

在標籤 格式 中，您可以使用具有 「全部」範圍的使用者定義和預先定義變數。例如：

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

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

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

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

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

報告組建狀態 （Azure Pipelines、TFS 2018 和更新版本）

您可以選擇讓小組從遠端來源存放庫檢視組建狀態。

如果您的來源位於專案中的 Azure Repos Git 存放庫，則此選項會在 [程序代碼] 頁面上顯示徽章，指出組建是否通過或失敗。 組建狀態會顯示在下列索引標籤中：

• 檔案：指出所選分支的最新組建狀態。
• 認可：指出每個認可的組建狀態（這需要為您的組建啟用持續整合 （CI） 觸發程式）。
• 分支：指出每個分支的最新組建狀態。

如果您在項目中針對同一個存放庫使用多個組建管線，您可以選擇為一或多個管線啟用此選項。 在多個管線上啟用此選項時，[程序代碼] 頁面上的徽章會指出所有管線中最新組建的狀態。 您的小組成員可以按兩下組建狀態徽章，檢視每個組建管線的最新組建狀態。

GitHub

如果您的來源位於 GitHub 中，則此選項會使用 GitHub 檢查或狀態 API，將組建的狀態發佈至 GitHub。 如果您的組建是從 GitHub 提取要求觸發的，您可以在 GitHub 提取要求頁面上檢視狀態。 這也可讓您在 GitHub 內設定狀態原則，並自動合併。 如果您的組建是由持續整合觸發的，則您可以在 GitHub 中的認可或分支上檢視組建狀態。

其他類型的 Git 遠端存放庫

如果您的來源位於任何其他遠端存放庫類型，則您無法使用 Azure Pipelines 或 TFS 自動將組建狀態發佈至該存放庫。 不過，您可以使用 組建徽章 作為在版本控制體驗中整合和顯示組建狀態的方式。

簽出路徑

如果您簽出單一存放庫，根據預設，您的原始程式碼會簽入名為 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\tools 和 C:\agent\_work\1\s\code。

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

如果您使用多個步驟並簽出多個 checkout 存放庫，而且想要使用 明確指定資料夾 path，請考慮避免設定另一個簽出步驟路徑的子資料夾 （亦即 C:\agent\_work\1\s\repo1 和 C:\agent\_work\1\s\repo1\repo2），否則，簽出步驟的子資料夾將會由另一個存放庫的清除清除清除。 請注意，如果的清除選項為 repo1true，則此案例有效。

注意

簽出路徑只能指定YAML管線。 如需詳細資訊，請參閱在 YAML 架構中籤出。

簽出子模組

如果您要從 子模組下載檔案，請選擇 。 您可以選擇取得立即子模組或巢狀至任何遞歸深度的所有子模組。 如果您想要搭配子模組使用 LFS，請務必查看 搭配子模組使用 LFS 的相關附注。

注意

如需有關簽出子模組之 YAML 語法的詳細資訊，請參閱 在 YAML 架構中籤出。

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

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

• 認證：

  • 包含在與上述 Git 存放庫相同的專案、GitHub 組織或 Bitbucket Cloud 帳戶中。

  • 使用相對於主要存放庫的網址來新增 。 例如，此檔案會取出： git submodule add /../../submodule.git mymodule 此檔案不會取出： git submodule add https://dev.azure.com/fabrikamfiber/_git/ConsoleApp mymodule

已驗證的子模組

注意

請確定您已使用 HTTPS 註冊您的子模組，而不使用 SSH。

代理程式用來從主要存放庫取得來源的相同認證也會用來取得子模組的來源。

如果您的主要存放庫和子模組位於 Azure DevOps 專案中的 Azure Repos Git 存放庫，則可以選取用來存取來源的帳戶。 在 [ 選項] 索引標籤的 [建置作業授權範圍 ] 選單上，選取下列其中一項：

• 使用專案集合建置服務帳戶的專案集合

• 使用專案建置服務帳戶的目前專案 。

請確定您使用的帳戶可以同時存取主要存放庫和子模組。

如果您的主要存放庫和子模組位於相同的 GitHub 組織中，則會使用儲存在 GitHub 服務連線中的令牌來存取來源。

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

在某些情況下，您無法使用 [結帳] 子模組 選項。 您可能有需要一組不同認證才能存取子模組的案例。 例如，如果您的主要存放庫和子模組存放庫未儲存在相同的 Azure DevOps 組織或 Git 服務中，就會發生這種情況。

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

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

請務必將 「<BASIC_AUTH_TOKEN>」 取代為您的 Base64 編碼令牌。

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

注意

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

從 LFS 取出檔案

如果您要從大型檔案記憶體下載檔案，請選擇取 。

在傳統編輯器中，選取複選框以啟用此選項。

在 YAML 組建中，新增已設定為 true的結帳步驟lfs：

steps:
- checkout: self
  lfs: true

如果您使用 TFS，或如果您使用 Azure Pipelines 搭配自我裝載的代理程式，則必須在 git-lfs 代理程式上安裝 ，才能讓此選項能夠運作。 如果您的託管代理程式使用 Windows，請考慮使用 System.PreferGitFromPath 變數，以確保管線使用您在計算機上安裝的 git 和 git-lfs 版本。 如需詳細資訊，請參閱 代理程序執行的 Git 版本為何？

搭配子模組使用 Git LFS

如果子模組包含 LFS 檔案，必須先設定 Git LFS，才能取出子模組。 Microsoft 裝載的 macOS 和 Linux 代理程式會以這種方式預先設定。 Windows 代理程式和自我裝載的macOS /Linux代理程式可能不是。

因應措施是，如果您使用 YAML，您可以在 之前 checkout新增下列步驟：

steps:
- script: |
    git config --global --add filter.lfs.required true
    git config --global --add filter.lfs.smudge "git-lfs smudge -- %%f"
    git config --global --add filter.lfs.process "git-lfs filter-process"
    git config --global --add filter.lfs.clean "git-lfs clean -- %%f"
  displayName: Configure LFS for use with submodules
- checkout: self
  lfs: true
  submodules: true
# ... rest of steps ...

複製第二個存放庫

根據預設，您的管線會與 Azure Repos 或外部提供者中的一個存放庫相關聯。 這是可在認可和提取要求上觸發建置的存放庫。

您可能想要在管線中包含來自第二個存放庫的來源。 您可以撰寫腳本來執行此動作。

git clone https://github.com/Microsoft/TypeScript.git

如果存放庫不是公用的，您必須將驗證傳遞至 Git 命令。

Azure Repos

您可以使用多存放庫簽出，在與管線相同的專案中複製多個存放庫。

如果您需要從非公用的另一個專案複製存放庫，您必須以具有該專案存取權的使用者身分進行驗證。

注意

使用秘密變數安全地儲存認證。

秘密變數不會自動提供給腳本做為環境變數。 如需如何對應秘密變數，請參閱 秘密變數 。

針對 Azure Repos，您可以使用個人存取權杖搭配 程式代碼 （讀取） 許可權。 以密碼欄位的形式傳送至 「基本」授權標頭中，而不需用戶名稱。 （換句話說，base64 編碼的值 :<PAT>，包括冒號。

AUTH=$(echo -n ":$REPO_PAT" | openssl base64 | tr -d '\n')
git -c http.<repo URL>.extraheader="AUTHORIZATION: basic $AUTH" clone <repo URL> --no-checkout --branch master

不要同步來源

非部署作業會自動擷取來源。 如果您想要略過該行為，請使用此選項。 當您想要下列情況時，此選項很有用：

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

• 使用建置管線來執行自動化（例如某些腳本），而不需要依賴版本控制中的程序代碼。

如果您要停用下載來源：

• Azure Pipelines、TFS 2018 和更新版本： 按兩下 [進階設定]，然後選取 [不要同步處理來源]。

注意

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

淺層

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

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

注意

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

選取複選框以啟用此選項之後，在 [深度 ] 方塊中指定認可數目。

提示

Agent.Source.Git.ShallowFetchDepth下面所述的變數也適用於並覆寫複選框控件。 如此一來，您就可以在將組建排入佇列時修改設定。

偏好從路徑取得 Git

根據預設，Windows 代理程式會使用隨附於代理程式軟體的 Git 版本。 Microsoft 建議使用隨附於代理程式的 Git 版本，但您有數個選項可覆寫此預設行為，並使用代理程式電腦已安裝在路徑中的 Git 版本。

• 在管線中將名為 System.PreferGitFromPath 的管線變數設定為 true 。
• 在自我裝載代理程式上，您可以在代理程式根目錄中建立名為 .env 的檔案，並將一 System.PreferGitFromPath=true 行新增至檔案。 如需詳細資訊，請參閱 如何? 為每個個別代理程式設定不同的環境變數？

若要查看管線所使用的 Git 版本，您可以查看管線中步驟的記錄 checkout ，如下列範例所示。

Syncing repository: PathFilter (Git)
Prepending Path environment variable with directory containing 'git.exe'.
git version
git version 2.26.2.windows.1

非 Windows 代理程式上此設定一律為 true。

其他 Git 的觸發程式選項

指定其他/外部 Git 存放庫時，CI 組建會要求可從因特網存取存放庫。 如果存放庫位於防火牆或 Proxy 後方，則只有排程和手動組建才能運作。

常見問題集

組建代理程式可以搭配 Git 使用哪些通訊協定？

代理程式支援 HTTPS。

代理程式尚不支援 SSH。 請參閱 允許組建在簽出 Git 子模組時使用 SSH 驗證。