建置 GitHub 存放庫

Azure DevOps Services

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

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

組織和使用者

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

組織

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

GitHub 組織結構

Azure DevOps 的結構是由包含專案的組織所組成。 請參閱 規劃組織結構

Azure DevOps 組織結構

Azure DevOps 可以使用:

  • GitHub組織或使用者帳戶的 DevOps組織
  • GitHub 存放的 DevOps Projects

對應至 Azure DevOps 的 GitHub 結構

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

  1. 建立名為 的 DevOps 組織,以您的 GitHub 組織或使用者帳戶命名。 它會有類似 https://dev.azure.com/your-organization 的 URL。
  2. 在 DevOps 組織中,建立以存放庫命名的專案。 它們會有類似 https://dev.azure.com/your-organization/your-repository 的 URL。
  3. 在 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) 。

DevOps 組織成員許可權位於 https://dev.azure.com/your-organization/_settings/security (取代 your-organization) 。

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

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

GitHub 使用者帳戶角色

GitHub 使用者帳戶有一個角色,也就是帳戶的擁有權。

DevOps 組織成員許可權位於 https://dev.azure.com/your-organization/_settings/security (取代 your-organization) 。

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

GitHub 使用者帳戶角色 DevOps 組織對等專案
擁有者 的成員 Project Collection Administrators

GitHub 存放庫許可權

GitHub 存放庫許可權位於 https://github.com/your-organization/your-repository/settings/collaboration (取代 your-organizationyour-repository) 。

DevOps 專案許可權位於 https://dev.azure.com/your-organization/your-project/_settings/security (取代 your-organizationyour-project) 。

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

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

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

管線特定許可權

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

  1. 流覽專案的 [管線] 頁面 (, https://dev.azure.com/your-organization/your-project/_build 例如) 。
  2. 選取要為其設定特定許可權的管線。
  3. 從 [...] 操作功能表中,選取 [安全性]。
  4. 選取 [新增...] 以新增特定使用者、小組或群組,並自訂管線的許可權。

存取 GitHub 存放庫

您可以先選取 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 應用程式會在安裝期間要求下列許可權:

權限 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 身分識別執行。 為了讓管線持續運作,您的存放庫存取權必須保持作用中。 OAuth 無法使用某些 GitHub 功能,例如 Checks,而且需要 GitHub 應用程式。

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

GitHub 中所需的許可權

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

  • 如果存放庫位於您的個人 GitHub 帳戶中,至少一次,請使用您的個人 GitHub 帳號憑證向 GitHub 進行驗證。 這可以在 [管線 > 服務連線 > ] 下的 [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 設定中的 個人存取權杖 。 必要的許可權為 repoadmin:repo_hookread:user 、 和 user:email 。 這些是上述使用 OAuth 時所需的相同許可權。 將產生的 PAT 複製到剪貼簿,並將其貼到 Azure DevOps 專案設定中的新 GitHub 服務連線 。 如需未來重新叫用,請在您的 GitHub 使用者名稱後面命名服務連線。 您可以在 Azure DevOps 專案中使用它,以供稍後在建立管線時使用。

GitHub 中所需的許可權

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

  • 如果存放庫位於您的個人 GitHub 帳戶中,PAT 必須具有 個人存取權杖底下的必要存取範圍: repoadmin:repo_hookread:useruser:email

  • 如果存放庫位於其他人的個人 GitHub 帳戶中,PAT 必須具有 個人存取權杖底下的必要存取範圍: repoadmin:repo_hookread:useruser:email 。 您必須在 [共同作業者] 底下的存放庫設定中新增為共同作業者。 使用傳送電子郵件給您的連結,接受邀請成為共同作業者。

  • 如果存放庫位於您擁有的 GitHub 組織中,PAT 必須具有 個人存取權杖底下的必要存取範圍: repoadmin:repo_hookread:useruser:email 。 您必須新增為共同作業者,或必須在存放庫的 [共同作業者和小組] 底下的存放庫設定中新增您的小組。

  • 如果存放庫位於其他人擁有的 GitHub 組織中,PAT 必須具有 個人存取權杖底下的必要存取範圍: repoadmin:repo_hookread:useruser:email 。 您必須新增為共同作業者,或必須在存放庫的 [共同作業者和小組] 底下的存放庫設定中新增您的小組。 使用傳送電子郵件給您的連結,接受邀請成為共同作業者。

撤銷 PAT 存取權

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

CI 觸發程式

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

YAML 管線預設會在所有分支上使用 CI 觸發程序進行設定。

分支

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

trigger:
- master
- releases/*

例如,您可以指定分支 (的完整名稱,例如, master) 或萬用字元 (,例如) releases/* 。 如需萬用字元語法的相關資訊,請參閱 通配 符。

注意

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

注意

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

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

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

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

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

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

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

如果您未指定任何觸發程式,預設值會像您撰寫一樣:

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:
    - master

注意

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

為了厘清此範例,讓我們假設推送 A 至 master 導致上述管線執行。 當管線正在執行時,額外的推送 BC 出現在存放庫中。 這些更新不會立即啟動新的獨立執行。 但在第一次執行完成之後,所有推播都會一起批次處理,並啟動新的執行。

注意

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

路徑

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

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

當您指定路徑時,必須明確指定要觸發的分支。 您無法只觸發路徑篩選準則的管線;您也必須有分支篩選準則,且符合路徑篩選準則的已變更檔案必須來自符合分支篩選準則的分支。

路徑篩選支援萬用字元。 例如,您可以包含符合 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 執行。

略過個別認可的 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:
    - master
    - releases/*
    - feature/*
    exclude:
    - releases/old*
    - feature/*-working
  paths:
    include:
    - docs/*.md

PR 觸發程式

提取要求 (PR) 觸發程式會導致每當使用其中一個指定目標分支開啟提取要求時,或對這類提取要求進行更新時,就會執行管線。

分支

您可以在驗證提取要求時指定目標分支。 例如,若要驗證目標 main 為 和 releases/* 的提取要求,您可以使用下列 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 具有分支子集的觸發程式時,只有在將更新推送至這些分支時,才會觸發管線。

如需需要排除特定分支的更複雜的觸發程式,您必須使用完整的語法,如下列範例所示。 在此範例中,提取要求會驗證目標 mainreleases/* ,而且會排除分支 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 組織成員。

  1. 首先,建立存放庫的管線,並至少建置一次,使其狀態張貼至 GitHub,藉此讓 GitHub 知道管線的名稱。

  2. 接下來,請遵循 GitHub 的檔,在存放庫的設定中 設定受保護的分支

    針對狀態檢查,請在 [ 狀態檢查 ] 清單中選取管線的名稱。

    GitHub 管線狀態檢查

重要

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

來自外部來源的貢獻

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

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

存取限制

當您在 Azure DevOps 公用專案中執行管線時,請注意下列存取限制:

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

分叉的貢獻

重要

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

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

  1. 移至您的 Azure DevOps 專案。 選取 [管線],找出您的管線,然後選取 [ 編輯]。
  2. 選取 [ 觸發程式] 索引標籤 。啟用 提取要求觸發程式之後,請啟用或停用 [從此存放庫分叉建置提取要求 ] 核取方塊。

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

若要略過 GitHub 管線上的此預防措施,請啟用 [ 讓秘密可供分叉組建 使用] 核取方塊。 請注意此設定對安全性的影響。

注意

當您啟用分支組建來存取秘密時,Azure Pipelines 預設會限制用於分叉組建的存取權杖。 相較于一般存取權杖,其對開啟資源的存取權會比較有限。 若要為分支組建提供與一般組建相同的許可權,請啟用 [建立分支組建] 具有與一般組建設定相同的許可權

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

重要安全性考量

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

  • 從管線洩漏秘密。 若要降低此風險,如果您的存放庫是公用或不受信任的使用者可以提交自動觸發組建的提取要求,請勿啟用 [ 讓分叉組建可以使用秘密 ] 核取方塊。 此選項預設為停用。

  • 危害執行代理程式的機器,以竊取來自其他管線的程式碼或秘密。 若要減輕此問題:

    • 使用 Microsoft 裝載的代理程式組件 區,從分叉建置提取要求。 Microsoft 裝載的代理程式機器會在完成組建之後立即刪除,因此如果遭到入侵,則不會有任何持續的影響。

    • 如果您必須使用 自我裝載代理程式,請勿儲存任何秘密,或執行在相同代理程式上使用秘密的其他組建和版本,除非您的存放庫是私人的,而且您信任提取要求建立者。

批註觸發程式

存放庫共同作業者可以批註提取要求,以手動執行管線。 以下是您可能想要執行此動作的一些常見原因:

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

若要啟用批註觸發程式,您必須遵循下列兩個步驟:

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

透過這兩項變更,提取要求驗證組建將不會自動觸發,除非 只選取來自非小組成員的提取要求 ,並由小組成員進行 PR。 只有具有 'Write' 許可權的存放庫擁有者和共同作業者可以藉由使用 或 /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 即將執行管線。

參考執行看起來像在下列螢幕擷取畫面中。

參考管線執行的螢幕擷取畫面。

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

  • 狀態為 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 。 如果不符合您的需求,您可以選擇排除內建簽出, checkout: none 然後使用腳本工作來執行您自己的簽出。

Git 的慣用版本

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

簽出路徑

如果您簽出單一存放庫,根據預設,您的原始程式碼會簽出到名為 的 s 目錄中。 針對 YAML 管線,您可以使用 來指定 checkout 來變更此專案 path 。 指定的路徑相對於 $(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 會導致有效的簽出路徑 (亦即 C:\agent\_work\1\anotherpath) ,但之類的 ..\invalidpath 值不會 (亦即 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 子模組:

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

  • 認證:

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

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

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

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

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

使用 [簽出] 子模組選項的替代方案

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

如果您無法使用 [簽出子模組 ] 選項,則可以改用自訂腳本步驟來擷取子模組。 首先, (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 認證管理員中通常無效,因為認證管理員可能會在更新子模組時提示您重新輸入認證。 使用者互動無法進行時,在自動化建置期間不需要這樣做。

同步標記

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

簽出存放庫時是否要同步處理標籤,方法是設定 fetchTags 屬性,以及在 UI 中設定 同步標記 設定。

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

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

steps:
- checkout: self
  fetchTags: true

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

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

    更多觸發程式功能表的螢幕擷取畫面。

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

    取得來源的螢幕擷取畫面。

  3. 設定 [同步標記] 設定。

    同步標記設定的螢幕擷取畫面。

注意

如果您在步驟中 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 管線,然後選擇 [更多動作]、[ 觸發程式]。

    更多觸發程式功能表的螢幕擷取畫面。

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

    取得來源的螢幕擷取畫面。

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

    選項的螢幕擷取畫面。

注意

如果您明確在步驟中 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

這會提供下列全新選項。

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

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

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

標籤來源

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

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

設定 Git 選項 YAML。

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

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

標籤格式 中,您可以使用具有 「All」 範圍的使用者定義和預先定義變數。例如:

$(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 Check Runs。 GitHub Checks 功能僅適用于 GitHub Apps。

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

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

PAT 或 OAuth GitHub 連線

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

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

GitHub 檢查

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

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

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

GitHub 檢查重新執行

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

常見問題集

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 應用程式,請遵循下列步驟:

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

為什麼 Azure Pipelines 中不會顯示 GitHub 存放庫,以供我選擇?

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

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

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

  1. 在 GitHub 存放庫中開啟提取要求,並提出批註 /azp where 。 這會回報存放庫所對應的 Azure DevOps 組織。

  2. 若要變更對應,請從 GitHub 組織卸載應用程式,然後重新安裝。 當您重新安裝時,請務必在重新導向至 Azure DevOps 時選取正確的組織。

失敗的觸發程式

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

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

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

    管線設定 UI。

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

    從這裡覆寫 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? 請參閱 連線類型 ,以判斷您擁有的連線類型。 如果您使用 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 檔案時覆寫觸發程式的分支清單。 如何執行該作業?

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

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

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

簽出失敗

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

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

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

錯誤的版本

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

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

遺漏狀態更新

GitHub 中的 PR 已遭到封鎖,因為 Azure Pipelines 未更新狀態。

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