建置 GitHub 存放庫

發行項
02/07/2024

Azure DevOps Services

Azure Pipelines 可以自動建置並驗證每個提取要求，並認可至您的 GitHub 存放庫。本文說明如何設定 GitHub 與 Azure Pipelines 之間的整合。

如果您不熟悉管線與 GitHub 整合，請遵循建立第一個管線中的步驟。回到本文，深入瞭解如何設定和自定義 GitHub 與 Azure Pipelines 之間的整合。

組織和使用者

GitHub 和 Azure Pipelines 是兩個獨立的服務，可整合在一起。他們每個人都有自己的組織和使用者管理。本節建議如何將組織和使用者從 GitHub 複寫至 Azure Pipelines。

組織

GitHub 的結構是由包含存放庫的組織和用戶帳戶所組成。請參閱 GitHub 的檔。

GitHub organization structure

Azure DevOps 的結構是由包含項目的組織所組成。請參閱規劃您的組織結構。

Azure DevOps organization structure

Azure DevOps 可以使用：

GitHub 組織或用戶帳戶的DevOps組織
GitHub 存放庫的 DevOps Projects

GitHub structure mapped to Azure DevOps

若要在 Azure DevOps 中設定相同的結構：

建立以 GitHub 組織或用戶帳戶命名的 DevOps 組織。其會有類似的 https://dev.azure.com/your-organizationURL。
在 DevOps 組織中，建立以存放庫命名的專案。它們會有類似的 https://dev.azure.com/your-organization/your-repositoryURL。
在 DevOps Project 中，建立以 GitHub 組織和建置存放庫命名的管線，例如 your-organization.your-repository。然後，很明顯它們要用於哪一個存放庫。

遵循此模式，您的 GitHub 存放庫和 Azure DevOps Projects 將會有相符的 URL 路徑。例如：

服務	URL
GitHub	`https://github.com/python/cpython`
Azure DevOps	`https://dev.azure.com/python/cpython`

使用者

您的 GitHub 使用者不會自動取得 Azure Pipelines 的存取權。 Azure Pipelines 不知道 GitHub 身分識別。因此，沒有任何方法可設定 Azure Pipelines，以使用其 GitHub 身分識別和電子郵件地址，自動通知使用者組建失敗或 PR 驗證失敗。您必須在 Azure Pipelines 中明確建立新使用者，才能復寫 GitHub 使用者。建立新用戶之後，您可以在 Azure DevOps 中設定其許可權，以在 GitHub 中反映其許可權。您也可以使用 DevOps 身分識別在 DevOps 中設定通知。

GitHub 組織角色

GitHub 組織成員角色位於 https://github.com/orgs/your-organization/people （取代 your-organization）。

在找到 https://dev.azure.com/your-organization/_settings/security DevOps 組織成員許可權（取代 your-organization）。

GitHub 組織中的角色和 Azure DevOps 組織中的對等角色如下所示。

GitHub 組織角色	DevOps 組織對等專案
負責人	的成員 `Project Collection Administrators`
帳單管理員	的成員 `Project Collection Administrators`
member	`Project Collection Valid Users`的成員。根據預設，成員群組缺少建立新項目的許可權。若要變更許可權，請將群組 `Create new projects` 的許可權設定為 `Allow`，或建立具有所需許可權的新群組。

GitHub 用戶帳戶角色

GitHub 用戶帳戶有一個角色，這是帳戶的擁有權。

在找到 https://dev.azure.com/your-organization/_settings/security DevOps 組織成員許可權（取代 your-organization）。

GitHub 用戶帳戶角色會對應至 DevOps 組織許可權，如下所示。

GitHub 用戶帳戶角色	DevOps 組織對等專案
負責人	的成員 `Project Collection Administrators`

GitHub 存放庫許可權

GitHub 存放庫許可權位於（replace your-organization 和 your-repository）中找到https://github.com/your-organization/your-repository/settings/collaboration。

DevOps 專案許可權位於（replace your-organization 和 your-project）中找到https://dev.azure.com/your-organization/your-project/_settings/security。

GitHub 存放庫與 Azure DevOps Projects 之間的對等許可權如下所示。

GitHub 存放庫許可權	DevOps 專案對等專案
管理	的成員 `Project Administrators`
寫入	的成員 `Contributors`
參閱	的成員 `Readers`

如果您的 GitHub 存放庫授與小組的許可權，您可以在 Azure DevOps 專案設定的區段中建立相符小組 Teams 。然後，將小組新增至上述安全組，就像用戶一樣。

管線特定許可權

若要將 DevOps 專案中特定管線的許可權授與使用者或小組，請遵循下列步驟：

瀏覽專案的 [管線] 頁面（例如）。 https://dev.azure.com/your-organization/your-project/_build
選取要設定特定許可權的管線。
從 [...] 操作功能表中，選取 [ 安全性]。
選取 [新增... ] 以新增特定使用者、小組或群組，並自定義管線的許可權。

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

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

Azure Pipelines 必須獲得存放庫的存取權，才能觸發其組建，並在組建期間擷取其程序代碼。

建立管線時，有三種驗證類型可用來授與GitHub 存放庫的存取權給 Azure Pipelines。

驗證類型	使用執行管線	使用 GitHub 檢查
1. GitHub 應用程式	Azure Pipelines 身分識別	Yes
2. OAuth	您的個人 GitHub 身分識別	No
3. 個人存取權杖（PAT）	您的個人 GitHub 身分識別	No

GitHub 應用程式驗證

Azure Pipelines GitHub 應用程式是 持續整合管線的建議 驗證類型。在 GitHub 帳戶或組織中安裝 GitHub 應用程式之後，您的管線將會執行，而不使用您的個人 GitHub 身分識別。組建和 GitHub 狀態更新將會使用 Azure Pipelines 身分識別來執行。應用程式可與 GitHub Checks 搭配運作，以在 GitHub 中顯示組建、測試和程式代碼涵蓋範圍結果。

若要使用 GitHub 應用程式，請在您的 GitHub 組織或使用者帳戶中安裝一些或所有存放庫。您可以從應用程式的首頁安裝並卸載 GitHub 應用程式。

安裝之後，當為存放庫建立管線時，GitHub 應用程式會變成 Azure Pipelines 對 GitHub 進行驗證的預設方法（而不是 OAuth）。

如果您在 GitHub 組織中安裝所有存放庫的 GitHub 應用程式，您不需要擔心 Azure Pipelines 會傳送大量電子郵件，或代表您自動設定管線。除了安裝所有存放庫的應用程式，存放庫系統管理員可以針對個別存放庫一次安裝一個存放庫。這需要系統管理員的更多工作，但沒有任何優勢或缺點。

GitHub 中所需的許可權

安裝 Azure Pipelines GitHub 應用程式需要您是 GitHub 組織擁有者或存放庫管理員。此外，若要為具有持續整合和提取要求觸發程式的 GitHub 存放庫建立管線，您必須設定必要的 GitHub 許可權。否則， 建立管線時，存放庫將不會出現在 存放庫清單中。根據存放庫的驗證類型和擁有權，確定已設定適當的存取權。

如果存放庫位於您的個人 GitHub 帳戶中，請在個人 GitHub 帳戶中安裝 Azure Pipelines GitHub 應用程式，而且您可以在 Azure Pipelines 中建立管線時列出此存放庫。
如果存放庫位於其他人的個人 GitHub 帳戶中，則其他人必須在其個人 GitHub 帳戶中安裝 Azure Pipelines GitHub 應用程式。您必須在「共同作業者」底下的存放庫設定中新增為共同作業者。使用傳送電子郵件給您的連結，接受邀請成為共同作業者。完成後，您可以建立該存放庫的管線。
如果存放庫位於您擁有的 GitHub 組織中，請在 GitHub 組織中安裝 Azure Pipelines GitHub 應用程式。您也必須新增為共同作業者，或您的小組必須新增至「共同作業者和小組」底下的存放庫設定中。
如果存放庫位於其他人擁有的 GitHub 組織中，GitHub 組織擁有者或存放庫管理員必須在組織中安裝 Azure Pipelines GitHub 應用程式。您必須新增為共同作業者，或您的小組必須新增至「共同作業者和小組」底下的存放庫設定中。使用傳送電子郵件給您的連結，接受邀請成為共同作業者。

GitHub 應用程式許可權

GitHub App 會在安裝期間要求下列許可權：

權限	Azure Pipelines 如何使用許可權
撰寫程式代碼的存取權	只有在您刻意採取行動時，Azure Pipelines 才會將 YAML 檔案認可至 GitHub 存放庫選取的分支，以簡化建立管線。
中繼資料的讀取權限	Azure Pipelines 會擷取 GitHub 元數據，以顯示組建摘要中與組建相關聯的存放庫、分支和問題。
檢查的讀取和寫入存取權	Azure Pipelines 將會讀取和寫入自己的組建、測試和程式代碼涵蓋範圍結果，以顯示在 GitHub 中。
提取要求的讀取和寫入存取權	只有在您刻意的動作時，Azure Pipelines 會建立已認可至 GitHub 存放庫所選取分支的 YAML 檔案提取要求，以簡化建立管線。管線會擷取要求元數據，以顯示在與提取要求相關聯的組建摘要中。

針對 GitHub 應用程式安裝進行疑難解答

GitHub 可能會顯示錯誤，例如：

You do not have permission to modify this app on your-organization. Please contact an Organization Owner.

這表示 GitHub 應用程式可能已經為您的組織安裝。當您在組織中建立存放庫的管線時，GitHub 應用程式會自動用來連線到 GitHub。

在多個 Azure DevOps 組織和專案中建立管線

安裝 GitHub 應用程式之後，即可為不同 Azure DevOps 組織和專案中的組織存放庫建立管線。不過，如果您在多個 Azure DevOps 組織中為單一存放庫建立管線，則 GitHub 認可或提取要求只能自動觸發第一個組織的管線。次要 Azure DevOps 組織中仍可進行手動或排程的組建。

OAuth 驗證

OAuth 是最簡單的驗證類型，可開始使用您個人 GitHub 帳戶中的存放庫。 GitHub 狀態更新將代表您的個人 GitHub 身分識別執行。若要讓管線持續運作，您的存放庫存取權必須保持作用中。某些 GitHub 功能，例如 Checks，無法使用 OAuth，而且需要 GitHub 應用程式。

若要使用 OAuth，請在建立管線時，選取 存放庫清單下方的不同連線 。然後，選取 [ 授權 ] 以登入 GitHub 並使用 OAuth 進行授權。 OAuth 連線將會儲存在 Azure DevOps 專案中以供稍後使用，並用於正在建立的管線中。

GitHub 中所需的許可權

若要為具有持續整合和提取要求觸發程式的 GitHub 存放庫建立管線，您必須設定必要的 GitHub 許可權。否則， 建立管線時，存放庫將不會出現在 存放庫清單中。根據存放庫的驗證類型和擁有權，確定已設定適當的存取權。

如果存放庫位於您的個人 GitHub 帳戶中，至少一次，請使用您的個人 GitHub 帳戶認證向 GitHub 進行 OAuth 驗證。這可以在 [管線服務連線>] 下的 [Azure > DevOps 項目設定] 中完成。新的服務連線 > GitHub > 授權。請在這裡將存放庫的存取權授與 Azure Pipelines。
如果存放庫位於其他人的個人 GitHub 帳戶中，至少一次，則其他人必須使用其個人 GitHub 帳戶認證向 GitHub 進行驗證。這可以在 [管線服務連線>] 下的 [Azure > DevOps 項目設定] 中完成。新的服務連線 > GitHub > 授權。其他人必須在這裡將存放庫的存取權授與 Azure Pipelines。您必須在「共同作業者」底下的存放庫設定中新增為共同作業者。使用傳送電子郵件給您的連結，接受邀請成為共同作業者。
如果存放庫位於您擁有至少一次的 GitHub 組織中，請使用您的個人 GitHub 帳戶認證向 GitHub 進行驗證。這可以在 [管線服務連線>] 下的 [Azure > DevOps 項目設定] 中完成。新的服務連線 > GitHub > 授權。在此將 Azure Pipelines 存取權授與貴組織的「組織存取權」。您必須新增為共同作業者，或您的小組必須新增至「共同作業者和小組」底下的存放庫設定中。
如果存放庫位於其他人擁有的 GitHub 組織中，至少擁有一次，GitHub 組織擁有者必須使用其個人 GitHub 帳戶認證向 GitHub 進行驗證。這可以在 [管線服務連線>] 下的 [Azure > DevOps 項目設定] 中完成。新的服務連線 > GitHub > 授權。組織擁有者必須在此的「組織存取權」底下，將組織的存取權授與 Azure Pipelines。您必須新增為共同作業者，或您的小組必須新增至「共同作業者和小組」底下的存放庫設定中。使用傳送電子郵件給您的連結，接受邀請成為共同作業者。

撤銷 OAuth 存取權

授權 Azure Pipelines 使用 OAuth 之後，若要稍後撤銷並防止進一步使用，請造訪 GitHub 設定中的 OAuth Apps 。您也可以從 Azure DevOps 項目設定中的 GitHub 服務連線清單刪除它。

個人存取令牌（PAT）驗證

PAT 實際上與 OAuth 相同，但可讓您控制授與 Azure Pipelines 的許可權。組建和 GitHub 狀態更新將代表您的個人 GitHub 身分識別執行。若要讓組建持續運作，您的存放庫存取權必須保持作用中。

若要建立 PAT，請流覽 GitHub 設定中的個人存取令牌。必要的權限為 repo、 admin:repo_hook、 read:user和 user:email。這些是上述使用 OAuth 時所需的相同許可權。將產生的 PAT 複製到剪貼簿，並將其貼到 Azure DevOps 專案設定中的新 GitHub 服務連線中。未來重新叫用時，請在您的 GitHub 使用者名稱後面命名服務連線。您可以在 Azure DevOps 專案中取得，以供稍後在建立管線時使用。

GitHub 中所需的許可權

若要為具有持續整合和提取要求觸發程式的 GitHub 存放庫建立管線，您必須設定必要的 GitHub 許可權。否則， 建立管線時，存放庫將不會出現在 存放庫清單中。根據存放庫的驗證類型和擁有權，確定已設定下列存取權。

如果存放庫位於您的個人 GitHub 帳戶中，PAT 必須具有個人存取令牌底下的必要存取範圍：repo、admin:repo_hook、 read:user和 user:email。
如果存放庫位於其他人的個人 GitHub 帳戶中，PAT 必須具有個人存取令牌底下的必要存取範圍：repo、、 admin:repo_hookread:user和。 user:email 您必須在「共同作業者」底下的存放庫設定中新增為共同作業者。使用傳送電子郵件給您的連結，接受邀請成為共同作業者。
如果存放庫位於您擁有的 GitHub 組織中，PAT 必須具有個人存取令牌底下的必要存取範圍：repo、admin:repo_hook、 read:user和 user:email。您必須新增為共同作業者，或您的小組必須新增至「共同作業者和小組」底下的存放庫設定中。
如果存放庫位於其他人擁有的 GitHub 組織中，PAT 必須具有個人存取令牌底下的必要存取範圍：repo、admin:repo_hook、 read:user和 user:email。您必須新增為共同作業者，或您的小組必須新增至「共同作業者和小組」底下的存放庫設定中。使用傳送電子郵件給您的連結，接受邀請成為共同作業者。

撤銷 PAT 存取權

授權 Azure Pipelines 使用 PAT 之後，若要稍後將其刪除並防止進一步使用，請造訪 GitHub 設定中的個人存取令牌。您也可以從 Azure DevOps 項目設定中的 GitHub 服務連線清單刪除它。

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 trigger git branches

略過個別認可的 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）觸發程式會導致管線執行。

YAML
傳統

分支

您可以在驗證提取要求時指定目標分支。例如，若要驗證以和 releases/*為目標main的提取要求，您可以使用下列pr觸發程式。

pr:
- main
- releases/*

此組態會在第一次建立新的提取要求時啟動新的執行，並在每次對提取要求進行更新之後啟動。

您可以指定分支的完整名稱（例如 main），或通配符（例如， releases/*。

注意

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

注意

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

GitHub 會在建立提取要求時建立新的 ref 。 ref 指向 合併認可，這是提取要求的來源和目標分支之間的合併程序代碼。 PR 驗證管線會建置這個 ref 指向的認可。這表示用來執行管線的 YAML 檔案也是來源與目標分支之間的合併。因此，您對提取要求來源分支中 YAML 檔案所做的變更可以覆寫目標分支中 YAML 檔案所定義的行為。

如果您的 YAML 檔案中未 pr 顯示任何觸發程式，則會自動為所有分支啟用提取要求驗證，就像您撰寫下列 pr 觸發程式一樣。此組態會在建立任何提取要求時觸發組建，以及認可進入任何使用中提取要求的來源分支時。

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

重要

當您指定 pr 具有分支子集的觸發程式時，只有在將更新推送至這些分支時，才會觸發管線。

如需需要排除特定分支的更複雜的觸發程式，您必須使用完整的語法，如下列範例所示。在此範例中，提取要求會驗證目標 main 或 releases/* ，且排除分支 releases/old* 。

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

路徑

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

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

提示：

Azure Pipelines 會在決定不會因為路徑排除規則而執行驗證組建時，將中性狀態張貼回 GitHub。這會為 GitHub 提供清楚的方向，指出 Azure Pipelines 已完成其處理。如需詳細資訊，請參閱略過組建時將中性狀態張貼至 GitHub。

路徑篩選現在支援通配符。

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

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

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

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

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

您無法在路徑中使用變數，因為變數會在運行時間評估（觸發程式引發之後）。

Azure Pipelines 會在決定不會因為路徑排除規則而執行驗證組建時，將中性狀態張貼回 GitHub。

多個 PR 更新

您可以指定PR的更多更新是否應該取消相同PR的進行中驗證執行。預設值為 true。

# auto cancel false
pr:
  autoCancel: false
  branches:
    include:
    - main

草稿 PR 驗證

根據預設，提取要求觸發程式會在草稿提取要求和提取要求上引發，這些要求已準備好進行檢閱。若要停用草稿提取要求的提取要求觸發程式，請將 drafts 屬性設定為 false。

pr:
  autoCancel: boolean # indicates whether additional pushes to a PR should cancel in-progress runs for the same PR. Defaults to true
  branches:
    include: [ string ] # branch names which will trigger a build
    exclude: [ string ] # branch names which will not
  paths:
    include: [ string ] # file paths which must match to trigger a build
    exclude: [ string ] # file paths which will not trigger a build
  drafts: boolean # whether to build draft PRs, defaults to true

退出退出PR驗證

您可以藉由指定 pr: none來完全退出提取要求驗證。

# no PR triggers
pr: none

如需詳細資訊，請參閱 YAML 架構中的 PR 觸發程式。

注意

pr如果您的觸發程式未引發，請遵循常見問題中的疑難解答步驟。

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

在PR目標分支上具有PR觸發程式的管線將會在合併認可上執行（提取要求的來源和目標分支之間的合併程式代碼），無論是否有訊息或描述包含[skip ci]的推送認可（或其任何變體）。
如果 沒有任何 訊息或描述包含 [skip ci] 其訊息或描述的推送認可，則由PR來源分支變更所觸發的管線（或其任何變體）。如果至少有一個推送認可包含 [skip ci]，管線將不會執行。

最後，合併PR之後，如果合併認可訊息或描述不包含 [skip ci] （或其任何變體），Azure Pipelines 將會執行推送至目標分支所觸發的 CI 管線。

受保護的分支

您可以使用以分支為目標的每個認可或提取要求執行驗證組建，甚至防止提取要求合併，直到驗證組建成功為止。

若要設定 GitHub 存放庫的必要驗證組建，您必須是其擁有者、具有管理員角色的共同作業者，或是具有寫入角色的 GitHub 組織成員。

首先，建立存放庫的管線，並建置它至少一次，使其狀態張貼至 GitHub，藉此讓 GitHub 知道管線的名稱。
接下來，請遵循 GitHub 的檔，在存放庫的設定中設定受保護的分支。

針對狀態檢查，請在 [狀態檢查] 列表中選取管線的名稱。

重要

如果您的管線未顯示在此清單中，請確定下列事項：

您使用的是 GitHub 應用程式驗證
您的管線在過去一周至少執行過一次

來自外部來源的貢獻

如果您的 GitHub 存放庫開放原始碼，您可以將 Azure DevOps 專案公開，讓任何人都可以檢視管線的建置結果、記錄和測試結果，而不需登入。當組織外部的使用者派生存放庫並提交提取要求時，他們可以檢視會自動驗證這些提取要求的組建狀態。

當接受來自外部來源的貢獻時，您應該記住下列考慮事項：在公用專案中使用 Azure Pipelines。

存取限制
驗證分叉的貢獻
重要的安全性考慮

存取限制

當您在 Azure DevOps 公用項目中執行管線時，請注意下列存取限制：

秘密： 根據預設，與管線相關聯的秘密無法提取分支的要求驗證。請參閱驗證分叉的貢獻。
跨專案存取： Azure DevOps 公用專案中的所有管線都會以受限於專案的存取令牌執行。公用專案中的管線只能存取專案內的組建成品或測試結果等資源，而不是在 Azure DevOps 組織的其他專案中存取。
Azure Artifacts 套件： 如果您的管線需要從 Azure Artifacts 存取套件，您必須明確將許可權 授與 Project Build Service 帳戶，才能存取套件摘要。

分叉的貢獻

重要

這些設定會影響管線的安全性。

當您建立管線時，系統會自動觸發從存放庫分支提取要求。您可以變更此行為，仔細考慮其如何影響安全性。若要啟用或停用此行為：

前往您的 Azure DevOps 專案。選取 [ 管線]，找出您的管線，然後選取 [ 編輯]。
選取 [ 觸發程式] 索引標籤 。啟用 提取要求觸發程式之後，請啟用或停用 [從此存放庫 分支建置提取要求] 複選框。

根據預設，GitHub 管線會提供與組建管線相關聯的秘密，無法提取分支的要求組建。這些秘密預設會使用 GitHub Enterprise Server 管線來啟用。秘密包括：

可存取 GitHub 存放庫的安全性令牌。
如果您的管線使用這些專案：
- 服務連線認證
- 來自安全檔案庫的檔案
- 建置標示為秘密的變數

若要略過 GitHub 管線上的此預防措施，請啟用 [讓秘密可供組建分支使用 ] 複選框。請注意此設定對安全性的影響。

注意

當您啟用分支組建來存取秘密時，Azure Pipelines 預設會限制用於分支組建的存取令牌。其存取權比一般存取令牌還有限。若要為分支組建提供與一般組建相同的許可權，請啟用 Make fork 組建與一般組建 設定相同的許可權。

如需詳細資訊，請參閱存放庫保護 - 分支。

您可以使用限制從分支 GitHub 存放庫提取要求控制，集中定義管線如何從分支 GitHub 存放庫建置 PR。其可在組織和專案層級取得。您可以選擇：

停用從分支存放庫建置提取要求
從分支存放庫安全地建置提取要求
自定義從分支存放庫建置提取要求的規則

Screenshot of centralized control settings for how pipelines build PRs from forked GitHub repositories.

從 Sprint 229 開始，為了改善管線的安全性， Azure Pipelines 不再自動從分支 GitHub 存放庫建置提取要求。對於新項目和組織，[限制從分支 GitHub 存放庫建置提取要求] 設定的預設值是 [停用從分支存放庫建置提取要求]。

當您從分岔存放庫選擇 [安全地建置提取要求] 選項時，所有管線、組織或整個專案都無法將秘密提供給分叉存放庫建置的 PR，無法讓這些組建具有與一般組建相同的許可權，而且必須由 PR 批注觸發。專案仍然可以決定 不允許 管線建置這類PR。

當您選擇 [ 自定義 ] 選項時，您可以定義如何限制管線設定。例如，當 PR 屬於非小組成員和非參與者時，您可以確定所有管線都需要批注，才能從分支 GitHub 存放庫建置 PR。但是，您可以選擇允許它們讓這類組建使用秘密。專案可以決定 不允許 管線建置這類PR，或安全地建置它們，或具有比組織層級所指定更嚴格的設定。

現有組織的控件已關閉。從 2023 年 9 月開始，新組織預設會從分岔存放庫安全地建置提取要求。

重要的安全性考慮

GitHub 使用者可以分支您的存放庫、變更存放庫，並建立提取要求來建議變更您的存放庫。此提取要求可能包含惡意代碼，以作為觸發組建的一部分執行。這類程式代碼可能會以下列方式造成傷害：

從您的管線洩漏秘密。若要降低此風險，如果您的存放庫是公用或不受信任的使用者，可以提交自動觸發組建的提取要求，請勿啟用 [讓秘密可供組建建 置使用] 複選框。此選項預設為停用。
入侵執行代理程式的機器，以從其他管線竊取程式代碼或秘密。若要減輕此問題：
- 使用 Microsoft 裝載的代理程式集區，從分支建置提取要求。 Microsoft 裝載的代理程式機器會在完成組建后立即刪除，因此，如果遭到入侵，則不會有持久的影響。
- 如果您必須使用自我裝載的代理程式，請勿儲存任何秘密，或執行在相同代理程式上使用秘密的其他組建和版本，除非您的存放庫是私人的，而且您信任提取要求建立者。

批注觸發程式

存放庫共同作業者可以批注提取要求，以手動執行管線。以下是您可能想要執行這項操作的一些常見原因：

在檢閱變更之前，您可能不想自動從未知的使用者建置提取要求。您希望其中一個小組成員先檢閱其程式代碼，然後執行管線。從分支存放庫建置貢獻的程式代碼時，這通常用來作為安全性措施。
您可能想要執行選擇性的測試套件或一個以上的驗證組建。

若要啟用批注觸發程式，您必須遵循下列兩個步驟：

啟用管線的提取要求觸發程式，並確定您未排除目標分支。
在 Azure Pipelines 入口網站中，編輯您的管線，然後選擇 [ 更多動作]、 [觸發程式]。然後，在 [提取要求驗證] 下，啟用 [建置提取要求之前需要小組成員的批注]。
- 在建置提取要求之前，選擇 [開啟所有提取要求 ] 以要求小組成員的批注。使用此工作流程時，小組成員會檢閱提取要求，並在提取要求被視為安全之後，以批注觸發組建。
- 只有在 非小組成員提出PR時，才選擇 [只在非小組成員 提出提取要求] 時，才需要小組成員的批注。在此工作流程中，小組成員不需要次要小組成員的檢閱來觸發組建。

透過這兩項變更，除非 選取非小組成員 的提取要求，而且由小組成員進行PR，否則不會自動觸發提取要求驗證組建。只有具有「寫入」許可權的存放庫擁有者和共同作業者可以藉由使用或 /AzurePipelines run <pipeline-name>對提取要求/AzurePipelines run加上批注來觸發組建。

下列命令可以發出至批注中的 Azure Pipelines：

Command	結果
`/AzurePipelines help`	顯示所有支援命令的說明。
`/AzurePipelines help <command-name>`	顯示指定命令的說明。
`/AzurePipelines run`	執行與此存放庫相關聯的所有管線，其觸發程式不會排除此提取要求。
`/AzurePipelines run <pipeline-name>`	除非指定的管線觸發程式排除此提取要求，否則執行指定的管線。

注意

為了簡潔起見，您可以使用來批注， /azp 而不是 /AzurePipelines。

重要

只有在管線使用 Azure Pipelines GitHub 應用程式時，才會在提取要求討論中顯示對這些命令的回應。

針對提取要求批注觸發程序進行疑難解答

如果您有必要的存放庫許可權，但您的批注不會觸發管線，請確定您的成員資格是 存放庫組織中的公用 ，或直接將自己新增為存放庫共同作業者。除非是直接共同作業者或屬於直接共同作業者，否則管線看不到私人組織成員。您可以在這裡將 GitHub 組織成員資格從私人變更為公用（以您的組織名稱取代 Your-Organization ）： https://github.com/orgs/Your-Organization/people。

參考性執行

信息執行會告訴您 Azure DevOps 無法擷取 YAML 管線的原始程式碼。原始程式碼擷取會在回應外部事件時發生，例如推送的認可。它也會在響應內部觸發程式時發生，例如，檢查是否有程式代碼變更，並啟動排程的執行。原始程式碼擷取可能會因為多個原因而失敗，而 Git 存放庫提供者經常要求節流。信息執行的存在不一定表示 Azure DevOps 會執行管線。

信息執行看起來像在下列螢幕快照中。

Screenshot of an informational pipeline run.

您可以辨識下列屬性所執行的資訊：

狀態為 Canceled
持續時間為 < 1s
執行名稱包含下列其中一個文字：
- Could not retrieve file content for {file_path} from repository {repo_name} hosted on {host} using commit {commit_sha}.
- Could not retrieve content for object {commit_sha} from repository {repo_name} hosted on {host}.
- Could not retrieve the tree object {tree_sha} from the repository {repo_name} hosted on {host}.
- Could not find {file_path} from repository {repo_name} hosted on {host} using version {commit_sha}. One of the directories in the path contains too many files or subdirectories.
執行名稱通常包含導致 YAML 管線載入失敗的 BitBucket / GitHub 錯誤
沒有階段 / 作業 / 步驟

深入瞭解信息執行。

結帳

觸發管線時，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。

簽出路徑

YAML
傳統

如果您簽出單一存放庫，根據預設，您的原始程式碼會簽入名為 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）。

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

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

Select the Clean setting.

來源：建置管線會執行中$(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]、[ 取得來源 ] 工作，然後在該處設定所需的屬性。

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} 的成品會自動新增至完成的組建。這可讓您的小組提供額外的可追蹤性和更方便使用的方式，從組建巡覽至所建置的程序代碼。卷標會被視為組建成品，因為它是由組建所產生。手動或透過保留原則刪除組建時，也會刪除標記。

預先定義的變數

當您建置 GitHub 存放庫時，大部分預先定義的變數都可供您的作業使用。不過，由於 Azure Pipelines 無法辨識在 GitHub 中進行更新的使用者身分識別，因此下列變數會設定為系統身分識別，而不是使用者的身分識別：

Build.RequestedFor
Build.RequestedForId
Build.RequestedForEmail

狀態更新

Azure Pipelines 會張貼回 GitHub 的兩種狀態類型 - 基本狀態和 GitHub 檢查執行。 GitHub Checks 功能僅適用於 GitHub Apps。

管線狀態會顯示在 GitHub UI 的各個位置。

針對PR，它們會顯示在 [PR 交談] 索引標籤上。
針對個別認可，當將滑鼠停留在存放庫認可索引標籤上的認可時間之後的狀態標記時，就會顯示這些認可。

PAT 或 OAuth GitHub 連線

針對使用 PAT 或 OAuth GitHub 連線的管線，狀態會張貼回觸發執行的認可/PR。 GitHub 狀態 API 可用來張貼這類更新。這些狀態包含有限的資訊：管線狀態（失敗、成功）、連結回組建管線的URL，以及狀態的簡短描述。

PAT 或 OAuth GitHub 連線的狀態只會在執行層級傳送。換句話說，您可以針對整個執行更新單一狀態。如果您在執行中有多個作業，則無法為每個作業張貼個別的狀態。不過，多個管線可以將不同的狀態張貼至相同的認可。

GitHub 檢查

針對使用 Azure Pipelines GitHub 應用程式設定的管線，狀態會以 GitHub Checks 的形式傳回。 GitHub 檢查允許傳送管線狀態和測試、程式代碼涵蓋範圍和錯誤的詳細資訊。您可以在這裡找到 GitHub 檢查 API。

針對每個使用 GitHub 應用程式的管線，檢查會針對整體執行和該執行中的每個作業傳回。

當一或多個 PR/認可檢查執行失敗時，GitHub 允許三個選項。您可以選擇「重新執行」個別的 Check、重新執行該 PR/認可的所有失敗檢查，或重新執行所有檢查，無論其一開始是否成功。

GitHub checks rerun

按兩下 [檢查執行名稱] 旁的 [重新執行] 連結，會導致 Azure Pipelines 重試產生 [檢查執行] 的執行。產生的執行將會有相同的執行號碼，而且會使用與初始組建相同的原始碼、組態和 YAML 檔案版本。只有初始執行中失敗的作業，且任何相依的下游作業將會再次執行。按兩下 [重新執行所有失敗的檢查] 連結將具有相同的效果。這與在 Azure Pipelines UI 中按兩下 [重試執行] 的行為相同。按兩下 [重新執行所有檢查] 會導致新的執行，並具有新的執行號碼，並會挑選組態或YAML檔案中的變更。

限制

為了獲得最佳效能，我們建議在單一存放庫中最多 50 個管線。為了獲得可接受的效能，我們建議在單一存放庫中最多100個管線。處理推送至存放庫所需的時間會隨著該存放庫中的管線數目而增加。每當推送至存放庫時，Azure Pipelines 必須載入該存放庫中的所有 YAML 管線，以找出其中是否有任何管線需要執行，而且載入每個管線會產生效能損失。除了效能問題之外，在單一存放庫中有太多管線可能會導致 GitHub 端的節流，因為 Azure Pipelines 可能會在短時間內提出太多要求。
在管線中使用延伸和包含範本會影響 Azure Pipelines 提出 GitHub API 要求的速率，並可能導致 GitHub 端的節流。在執行管線之前，Azure Pipelines 必須產生完整的 YAML 程式代碼，因此需要擷取所有範本檔案。
Azure Pipelines 最多會將 2000 個分支從存放庫載入 Azure Devops 入口網站中的下拉式清單，例如手動和排程組建設定的預設分支，或在手動執行管線時選擇分支時。如果您沒有在清單中看到所需的分支，請手動輸入所需的分支名稱。

常見問題集

GitHub 整合的相關問題分為下列類別：

連線類型：我不確定我用來將管線連線到 GitHub 的連接類型。
失敗的觸發程式： 當我將更新推送至存放庫時，我的管線不會觸發。
簽出失敗：正在觸發我的管線，但在簽出步驟中失敗。
錯誤的版本： 我的管線會執行，但它使用非預期的來源/YAML 版本。
遺失狀態更新： 我的 GitHub PR 因為 Azure Pipelines 未回報狀態更新而遭到封鎖。

連線類型

若要針對觸發程式進行疑難解答，如何知道我用於管線的 GitHub 連線類型？

針對觸發程式的問題進行疑難解答在很大程度上取決於您在管線中使用的 GitHub 連線類型。有兩種方式可以判斷連線類型 - 從 GitHub 和 Azure Pipelines。

從 GitHub：如果存放庫設定為使用 GitHub 應用程式，則 PR 和認可的狀態會是 [檢查執行]。如果存放庫已使用 OAuth 或 PAT 連線來設定 Azure Pipelines，狀態會是狀態的「舊」樣式。判斷狀態是否為 [檢查執行] 或簡單狀態的快速方式，就是查看 GitHub PR 上的 [交談] 索引標籤。
- 如果 [詳細數據] 連結會重新導向至 [檢查] 索引標籤，則會是 [檢查執行]，而存放庫正在使用應用程式。
- 如果 [詳細數據] 連結會重新導向至 Azure DevOps 管線，則狀態為「舊樣式」狀態，且存放庫未使用應用程式。
從 Azure Pipelines：您也可以藉由檢查 Azure Pipelines UI 中的管線來判斷連線的類型。開啟管線的編輯器。選取 [觸發程式 ] 以開啟管線的傳統編輯器。然後，選取 [YAML] 索引標籤，然後選取 [取得來源] 步驟。您會注意到使用連線授權的橫幅：指出用來整合管線與 GitHub 的服務連線。服務連接的名稱是超連結。選取它以流覽至服務連線屬性。服務連線的屬性會指出所使用的連線類型：
- Azure Pipelines 應用程式 指出 GitHub 應用程式連線
- oauth 表示 OAuth 連線
- personalaccesstoken 表示 PAT 驗證

如何? 將管線切換為使用 GitHub 應用程式，而不是 OAuth？

使用 GitHub 應用程式，而不是 OAuth 或 PAT 連線，是 GitHub 與 Azure Pipelines 之間的建議整合。若要切換至 GitHub 應用程式，請遵循下列步驟：

瀏覽這裡，並在存放庫的 GitHub 組織中安裝應用程式。
在安裝期間，系統會將您重新導向至 Azure DevOps，以選擇 Azure DevOps 組織和專案。選擇包含您想要使用應用程式之傳統建置管線的組織與專案。這個選項會將 GitHub 應用程式安裝與您的 Azure DevOps 組織產生關聯。如果您選擇不正確，您可以瀏覽此頁面，從 GitHub 組織卸載 GitHub 應用程式，然後重新開始。
在下一個出現的頁面中，您不需要繼續建立新的管線。
流覽 [管線] 頁面來編輯管線（例如 https://dev.azure.com/YOUR_ORG_NAME/YOUR_PROJECT_NAME/_build)，選取您的管線，然後按兩下 [編輯]。
如果這是 YAML 管線，請選取 [ 觸發程式 ] 功能表以開啟傳統編輯器。
選取管線中的 [取得來源] 步驟。
在綠色列上，選取 [已授權使用連線] 文字，選取 [變更]，然後選取與安裝應用程式之 GitHub 組織同名的 GitHub 應用程式連線。
在工具欄上，選取 [儲存和佇列]，然後選取 [儲存和佇列]。選取已排入佇列的管線執行連結，以確定其成功。
在 GitHub 存放庫中建立提取要求（或關閉並重新開啟），以確認組建在其「檢查」區段中已成功排入佇列。

為什麼 Azure Pipelines 中沒有顯示 GitHub 存放庫供我選擇？

視存放庫的驗證類型和擁有權而定，需要特定許可權。

如果您使用 GitHub 應用程式，請參閱 GitHub 應用程式驗證。
如果您使用 OAuth，請參閱 OAuth 驗證。
如果您使用 PAT，請參閱個人存取令牌（PAT）驗證。

當我在管線建立期間選取存放庫時，我收到錯誤「存放庫 {repo-name} 正在與另一個 Azure DevOps 組織中的 Azure Pipelines GitHub 應用程式搭配使用」錯誤。

這表示您的存放庫已經與不同組織中的管線相關聯。來自此存放庫的 CI 和 PR 事件將無法運作，因為它們會傳遞至其他組織。以下是在繼續建立管線之前，移除對應至其他組織所應採取的步驟。

在您的 GitHub 存放庫中開啟提取要求，並提出批注 /azp where。這會回報存放庫所對應的 Azure DevOps 組織。
若要變更對應，請從 GitHub 組織卸載應用程式，然後重新安裝。當您重新安裝時，請務必在重新導向至 Azure DevOps 時選取正確的組織。

失敗的觸發程式

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

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

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

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

您是否使用 GitHub 應用程式連線將管線連線至 GitHub？請參閱連線類型來判斷您擁有的連接類型。如果您使用 GitHub 應用程式連線，請遵循下列步驟：
- GitHub 與 Azure DevOps 之間的對應是否已正確設定？在您的 GitHub 存放庫中開啟提取要求，並提出批注 /azp where。這會回報存放庫所對應的 Azure DevOps 組織。
  - 如果未設定任何組織以使用應用程式建置此存放庫，請移至 https://github.com/<org_name>/<repo_name>/settings/installations 並完成應用程式的設定。
  - 如果回報不同的 Azure DevOps 組織，則有人已在不同的組織中建立此存放庫的管線。我們目前有限制，我們只能將 GitHub 存放庫對應至單一 DevOps 組織。只有第一個 Azure DevOps 組織中的管線可以自動觸發。若要變更對應，請從 GitHub 組織卸載應用程式，然後重新安裝。當您重新安裝時，請務必在重新導向至 Azure DevOps 時選取正確的組織。
您是否使用 OAuth 或 PAT 將管線連線至 GitHub？請參閱連線 ion 類型，以判斷您擁有的連接類型。如果您使用 GitHub 連線，請遵循下列步驟：
1. OAuth 和 PAT 連線依賴 Webhook 來與 Azure Pipelines 通訊更新。在 GitHub 中，流覽至存放庫的設定，然後流覽至 Webhook。確認 Webhook 存在。通常您應該會看到三個 Webhook - 推送、pull_request和issue_comment。如果您未這麼做，則必須重新建立服務連線，並更新管線以使用新的服務連線。
2. 選取 GitHub 中的每個 Webhook，並確認對應至使用者認可的承載存在，且已成功傳送至 Azure DevOps。如果無法將事件傳達給 Azure DevOps，您可能會在這裡看到錯誤。
來自 Azure DevOps 的流量可能會受到 GitHub 的節流。當 Azure Pipelines 從 GitHub 收到通知時，會嘗試連絡 GitHub 並擷取存放庫和 YAML 檔案的詳細資訊。如果您有具有大量更新和提取要求的存放庫，此呼叫可能會因為這類節流而失敗。在此情況下，請參閱您是否可以使用批處理或更嚴格的路徑/分支篩選來減少組建的頻率。

管線已暫停或停用嗎？開啟管線的編輯器，然後選取要檢查設定。如果您的管線已暫停或停用，則觸發程式無法運作。
您是否已在正確的分支中更新 YAML 檔案？如果您將更新推送至分支，則相同分支中的 YAML 檔案會控管 CI 行為。如果您將更新推送至來源分支，則合併來源分支與目標分支所產生的 YAML 檔案會控管 PR 行為。請確定正確分支中的 YAML 檔案具有必要的 CI 或 PR 組態。
您是否已正確設定觸發程式？當您定義 YAML 觸發程式時，您可以同時指定分支、標記和路徑的 include 和 exclude 子句。請確定 include 子句符合認可的詳細數據，而且 exclude 子句不會排除這些子句。檢查觸發程式的語法，並確定其正確無誤。
您是否在定義觸發程式或路徑時使用變數？不支援。
您是否使用 YAML 檔案的樣本？如果是，請確定您的觸發程式定義於主要 YAML 檔案中。不支援範本檔案內定義的觸發程式。
您是否已排除您推送變更的分支或路徑？將變更推送至內含分支中的包含路徑，以進行測試。請注意，觸發程式中的路徑會區分大小寫。在指定觸發程式中的路徑時，請務必使用與實際資料夾相同的案例。
您剛推送新分支嗎？如果是，新分支可能不會啟動新的執行。請參閱一節。

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

首先，請流覽上一個問題中的疑難解答步驟，然後遵循下列其他步驟：

您的PR中有合併衝突嗎？若為未觸發管線的PR，請開啟它並檢查是否有合併衝突。解決合併衝突。
您遇到推送或 PR 事件的處理延遲嗎？您通常會查看問題是否為單一管線的特定問題，或是您專案中所有管線或存放庫通用，來驗證延遲。如果任何存放庫的推送或PR更新都表現出此徵兆，我們可能會遇到處理更新事件的延遲。以下是延遲可能發生的一些原因：
- 我們在狀態頁面上遇到服務中斷。如果狀態頁面顯示問題，則我們的小組必須已經開始處理。請經常檢查頁面，以取得問題的更新。
- 您的存放庫包含太多 YAML 管線。為了獲得最佳效能，我們建議在單一存放庫中最多 50 個管線。為了獲得可接受的效能，我們建議在單一存放庫中最多100個管線。有的管線越多，推送至該存放庫的處理速度就越慢。每當推送至存放庫時，Azure Pipelines 必須載入該存放庫中的所有 YAML 管線，以找出其中是否有任何管線需要執行，而且每個新管線都會產生效能損失。

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

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

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

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

簽出失敗

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

remote: Repository not found.
fatal: repository <repo> not found

這可能是因為 GitHub 中斷所造成。嘗試存取 GitHub 中的存放庫，並確定您能夠存取。

錯誤的版本

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

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

遺漏狀態更新

由於 Azure Pipelines 未更新狀態，因此封鎖了 GitHub 中的 PR。

這可能是暫時性錯誤，導致 Azure DevOps 無法與 GitHub 通訊。如果您使用 GitHub 應用程式，請重試簽入 GitHub。或者，對 PR 進行簡單的更新，以查看問題是否可以解決。

建置 GitHub 存放庫

組織和使用者

組織

使用者

GitHub 組織角色

GitHub 用戶帳戶角色

GitHub 存放庫許可權

管線特定許可權

存取 GitHub 存放庫

GitHub 應用程式驗證

GitHub 中所需的許可權

GitHub 應用程式許可權

針對 GitHub 應用程式安裝進行疑難解答

在多個 Azure DevOps 組織和專案中建立管線

OAuth 驗證

GitHub 中所需的許可權

撤銷 OAuth 存取權

個人存取令牌 （PAT） 驗證

GitHub 中所需的許可權

撤銷 PAT 存取權

CI 觸發程式

分支

批處理 CI 執行

路徑

標籤

退出宣告 CI

停用 CI 觸發程式

略過個別認可的 CI

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

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

萬用字元

PR 觸發程式

分支

路徑

多個 PR 更新

草稿 PR 驗證

退出退出PR驗證

受保護的分支

來自外部來源的貢獻

存取限制

分叉的貢獻

重要的安全性考慮

批注觸發程式

針對提取要求批注觸發程序進行疑難解答

參考性執行

結帳

Git 的慣用版本

簽出路徑

子模組

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

同步標記

預設行為

淺層

不要同步來源

清除組建

標籤來源

預先定義的變數

狀態更新

PAT 或 OAuth GitHub 連線

GitHub 檢查

限制

常見問題集

連線類型

若要針對觸發程式進行疑難解答，如何知道我用於管線的 GitHub 連線類型？

如何? 將管線切換為使用 GitHub 應用程式，而不是 OAuth？

為什麼 Azure Pipelines 中沒有顯示 GitHub 存放庫供我選擇？

當我在管線建立期間選取存放庫時，我收到錯誤「存放庫 {repo-name} 正在與另一個 Azure DevOps 組織中的 Azure Pipelines GitHub 應用程式搭配使用」錯誤。

失敗的觸發程式

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

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

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

簽出失敗

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

錯誤的版本

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

遺漏狀態更新

由於 Azure Pipelines 未更新狀態，因此封鎖了 GitHub 中的 PR。

相關文章

意見反應

意見反應

個人存取令牌（PAT）驗證

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

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

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

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