建置 GitHub 存放庫

Azure Pipelines

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

如果您不熟悉 Azure Pipelines 與 GitHub 整合,請依照建立第一個管線中的步驟,讓第一個管線使用 GitHub 存放庫,然後再回到本文,以深入瞭解如何設定和自訂 GitHub 與 Azure Pipelines 之間的整合。

組織和使用者

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

組織

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

GitHub 的組織結構

Azure DevOps ' 結構包含了包含 專案組織。 請參閱 規劃組織結構

Azure DevOps 的組織結構

Azure DevOps 可以使用下列內容反映您的 GitHub 結構:

  • 適用于您 GitHub 組織或使用者帳戶 的 Azure DevOps 組織
  • Azure DevOps GitHub 存放庫專案

對應至 Azure DevOps 的 GitHub 結構

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

  1. 建立以您的 GitHub 組織或使用者帳戶命名的 Azure DevOps 組織。 它會有類似的 URL https://dev.azure.com/your-organization
  2. 在 Azure DevOps 組織中,建立以您的存放庫命名的專案。 它們會有類似的 Url https://dev.azure.com/your-organization/your-repository
  3. 在 Azure DevOps Project 中,建立以其建立的 GitHub 組織和儲存機制命名的管線,例如 your-organization.your-repository 。 然後,它會清除它們所屬的存放庫。

遵循此模式,您的 GitHub 存放庫和 Azure DevOps 專案將會有相符的 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 中的許可權。 您也可以使用其 Azure DevOps 身分識別,在 Azure DevOps 中設定通知。

GitHub 組織角色

GitHub 組織成員角色可在 https://github.com/orgs/your-organization/people (取代) 中找到 your-organization

Azure DevOps 組織成員許可權可在 https://dev.azure.com/your-organization/_settings/security (取代) 中找到 your-organization

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

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

GitHub 使用者帳戶角色

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

Azure DevOps 組織成員許可權可在 https://dev.azure.com/your-organization/_settings/security (取代) 中找到 your-organization

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

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

GitHub 存放庫許可權

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

Azure DevOps 專案許可權可在 https://dev.azure.com/your-organization/your-project/_settings/security (取代 your-organization 和) 找到 your-project

GitHub 存放庫和 Azure DevOps 專案之間的同等許可權如下所示。

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

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

管線特定許可權

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

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

存取 GitHub 儲存機制

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

您稍後可以設定管線以簽出不同的存放庫或多個存放庫。 若要瞭解如何進行,請參閱 多個存放庫結帳。

Azure Pipelines 必須被授與存取權給您的儲存機制,以觸發其組建,並在組建期間提取其程式碼。

有3種驗證類型可在建立管線時授與 GitHub 存放庫的 Azure Pipelines 存取權。

驗證類型 使用 Pipelines 執行 適用于GitHub 檢查
1. GitHub 應用程式 Azure Pipelines 身分識別
2. OAuth 您個人的 GitHub 身分識別
3. 個人存取權杖 (PAT) 您個人的 GitHub 身分識別

GitHub 應用程式驗證

Azure Pipelines GitHub 應用程式是持續整合管線的 建議 驗證類型。 藉由將 GitHub 應用程式安裝在您的 GitHub 帳戶或組織內,您的管線就可以在不使用個人 GitHub 身分識別的情況下執行。 組建和 GitHub 狀態更新會使用 Azure Pipelines 身分識別來執行。 應用程式會搭配GitHub 檢查來顯示組建、測試和程式碼涵蓋範圍結果 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 帳戶中,則另一位人員必須將 Azure Pipelines GitHub 應用程式安裝在其個人的 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 檔案建立提取要求,以簡化管線的建立作業。 Azure Pipelines 將會取得提取要求中繼資料,以顯示在與提取要求相關聯的組建摘要中。

針對 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 功能(例如檢查)無法搭配 OAuth 使用,且需要 GitHub 應用程式。

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

GitHub 所需的許可權

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

  • 如果存放庫位於您個人的 GitHub 帳戶中(至少一次),請使用您的個人 GitHub 帳號憑證,向 OAuth 驗證 GitHub。 這可以在 Azure DevOps 的專案設定中完成,Pipelines > 服務連線 > 新的服務連接 > GitHub 授權。 在這裡授與 Azure Pipelines 存取您存放庫的許可權。

  • 如果存放庫位於他人的個人 GitHub 帳戶(至少一次),則其他人必須使用其個人 GitHub 帳號憑證,向 OAuth 進行驗證 GitHub。 這可以在 Azure DevOps 的專案設定中完成,Pipelines > 服務連線 > 新的服務連接 > GitHub 授權。 另一位人員必須授與 Azure Pipelines 存取其存放庫的許可權。 您必須在 [共同作業者] 下的存放庫設定中,將您新增為共同作業者。 使用透過電子郵件傳送給您的連結,接受邀請成為共同作業者。

  • 如果存放庫位於您所擁有的 GitHub 組織(至少一次),請使用您的個人 GitHub 帳號憑證,向 OAuth 驗證 GitHub。 這可以在 Azure DevOps 的專案設定中完成,Pipelines > 服務連線 > 新的服務連接 > GitHub 授權。 在這裡將 Azure Pipelines 存取權授與您的組織。 您必須新增為共同作業者,或您的小組必須新增至 [共同作業者和小組] 下的存放庫設定。

  • 如果存放庫位於他人所擁有的 GitHub 組織(至少一次),則 GitHub 組織擁有者必須使用其個人的 GitHub 帳號憑證,向 OAuth 進行驗證 GitHub。 這可以在 Azure DevOps 的專案設定中完成,Pipelines > 服務連線 > 新的服務連接 > GitHub 授權。 組織擁有者必須將 Azure Pipelines 存取權授與[組織中 組織存取] 下的組織。 您必須新增為共同作業者,或您的小組必須新增至 [共同作業者和小組] 下的存放庫設定。 使用透過電子郵件傳送給您的連結,接受邀請成為共同作業者。

撤銷 OAuth 存取權

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

個人存取權杖 (PAT) 驗證

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

若要建立 PAT,請造訪 GitHub 設定中的個人存取權杖。 必要的許可權為 repoadmin:repo_hookread:useruser: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_hook 、、 read:useruser:email 。 您必須新增為共同作業者,或您的小組必須新增至 [共同作業者和小組] 下的存放庫設定。

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

撤銷 PAT 存取權

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

CI 觸發程式

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

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

分支

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

trigger:
- master
- releases/*

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

注意

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

注意

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

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

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

在上述範例中,如果將變更推送至主機或任何發行分支,則會觸發管線。 但是,如果對開頭為的發行分支進行了變更,則不會觸發此程式 old

如果您指定 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

重要

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

批次處理 CI 執行

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

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

為了說明此範例,請讓我們假設推送 A 至主機造成上述管線執行。 當該管線正在執行時, B 會進行額外的推送,並 C 在存放庫中進行。 這些更新不會立即啟動新的獨立執行。 但在第一次執行完成後,所有推播都會將該時間點批次處理在一起,並啟動新的執行。

注意

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

路徑

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

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

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

祕訣:

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

標籤

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

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

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

重要

如果您指定與分支篩選組合的標記,則如果已滿足分支篩選或符合標記篩選器,就會引發觸發程式。 例如,如果推送的標記滿足分支篩選準則,則即使標記已被標記篩選器排除,管線也會觸發,因為推送已滿足分支篩選。

退出 CI

停用 CI 觸發程式

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

# A pipeline with no CI trigger
trigger: none

重要

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

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

略過個別認可的 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"
  • 針對分支、標記和路徑,萬用字元可能會出現在模式中的任何位置。
trigger:
  branches:
    include:
    - master
    - releases/*
    - feature/*
    exclude:
    - releases/old*
    - feature/*-working
  paths:
    include:
    - docs/*.md

PR 觸發程式

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

分支

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

pr:
- master
- releases/*

這項設定會在第一次建立新的提取要求,以及每次對提取要求進行更新之後,啟動新的執行。

您可以指定分支的完整名稱 (例如 master) 或萬用字元 (例如 releases/*) 。

注意

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

注意

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

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

如果 pr YAML 檔中沒有出現任何觸發程式,則所有分支都會自動啟用提取要求驗證,就像您撰寫下列 pr 觸發程式一樣。 這項設定會在任何提取要求建立時觸發組建,而且當認可進入任何作用中提取要求的來源分支時。

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

重要

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

對於需要排除特定分支的更複雜的觸發程式,您必須使用完整語法,如下列範例所示。

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

路徑

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

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

祕訣:

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

多個 PR 更新

您可以指定 PR 的其他更新是否應針對相同的 PR 取消進行中的驗證執行。 預設為 true

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

草稿 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 的觸發程式未引發,請依照 常見問題中的疑難排解步驟進行。

注意

草稿提取要求 不會觸發管線。

受保護的分支

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

若要設定 GitHub 儲存機制的強制驗證組建,您必須是其擁有者、具有系統管理員角色的共同作業者,或是具有寫入角色的 GitHub 組織成員。

  1. 首先,建立存放庫的管線,並至少建立一次,以便將其狀態張貼至 GitHub,進而讓 GitHub 知道管線的名稱。

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

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

    GitHub 管線狀態檢查

重要

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

外部來源的投稿

如果您的 GitHub 存放庫是開放原始碼,您可以讓您的 Azure DevOps 專案公開,讓任何人都能在不登入的情況下,查看您的管線組建結果、記錄和測試結果。 當組織外部的使用者將您的存放庫分叉並提交提取要求時,他們可以查看自動驗證這些提取要求的組建狀態。

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

存取限制

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

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

分支的投稿

重要

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

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

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

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

  • 可存取 GitHub 存放庫的安全性權杖。
  • 如果您的管線使用這些專案:

若要在 GitHub 管線上略過這項預防措施,請啟用 [將秘密提供給分支的組建] 核取方塊。 請注意這項設定對安全性的影響。

重要安全性考量

GitHub 的使用者可以將您的存放庫派生、變更,以及建立提取要求,以建議變更您的儲存機制。 此提取要求可能包含要在觸發的組建中執行的惡意程式碼。 這類程式碼可能會以下列方式造成危害:

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

  • 入侵執行代理程式的電腦,以竊取其他管線的程式碼或秘密。 若要減輕這個問題:

    • 使用 Microsoft 裝載的 代理程式組件 區,從分支建立提取要求。 Microsoft 裝載的代理程式電腦會在完成組建之後立即刪除,所以如果遭到入侵,就不會有任何持續的影響。

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

批註觸發程式

存放庫共同作業者可以對提取要求進行批註,以手動執行管線。 以下是您可能會想要這麼做的幾個常見原因:

  • 您可能不想要自動建立來自未知使用者的提取要求,直到可以審核其變更為止。 您希望您的其中一個小組成員先檢查其程式碼,然後再執行管線。 這在從分支存放庫建立貢獻的程式碼時,通常會用來做為安全性措施。
  • 您可能會想要執行選擇性的測試套件或其他驗證組建。

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

  1. 啟用管線的提取要求觸發程式,並確定您未排除目標分支。
  2. 在 Azure Pipelines 入口網站中,編輯您的管線,然後選擇 [其他動作]、[觸發 程式]。 然後,在 [ 提取要求驗證] 底下,先啟用 [ 需要小組成員的批註],再建立提取要求
    • 在建立提取要求之前,請 在所有提取要求上 選擇以要求小組成員的批註。 使用此工作流程時,小組成員會在提取要求被視為安全之後,使用批註來審核提取要求並觸發組建。
    • 只有當非小組成員提出 PR 時, 才需要從非小組成員的提取要求中 選擇,才需要小組成員的批註。 在此工作流程中,小組成員不需要次要小組成員的評論來觸發組建。

有了這兩項變更,就不會自動觸發提取要求驗證組建,除非選取了 非小組成員的提取要求 ,且 PR 是由小組成員所建立。 只有具有「寫入」許可權的存放庫擁有者和共同作業者可以使用或對提取要求進行批註,以觸發組建 /AzurePipelines run /AzurePipelines run <pipeline-name>

您可以對批註中的 Azure Pipelines 發出下列命令:

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

注意

為了簡潔起見,您可以使用 /azp 來批註,而不是 /AzurePipelines

重要

只有當您的管線使用Azure Pipelines GitHub 應用程式時,這些命令的回應才會出現在提取要求討論中。

針對提取要求批註觸發程式進行疑難排解

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

簽出

觸發管線時,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) 。 例如:如果簽出路徑值為 mycustompath$(Agent.BuildDirectory) 為,則 C:\agent\_work\1 會簽出原始程式碼 C:\agent\_work\1\mycustompath

如果您使用多個 checkout 步驟,並簽出多個存放庫,但未使用明確地指定資料夾,則 path 每個存放庫都會放置於儲存機制後面的命名子資料夾中 s 。 例如,如果您簽出兩個名為 tools 和的存放庫 code ,則會將原始程式碼簽出至 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 組織中) (的存放庫,但在不同的專案中 (FabrikamFiberProject) 。 代理程式用來從主要儲存機制取得來源的相同認證也會用來取得子模組的來源。 這需要作業存取權杖可以存取第二個專案中的存放庫。 如果您限制了作業存取權杖(如上述章節所述),則無法這麼做。 您可以藉由 () 在第二個專案中明確授與專案組建服務帳戶的存取權,) (或使用集合範圍存取權杖(而不是整個組織的專案範圍標記),來允許作業存取權杖存取第二個專案中的存放庫。 如需這些選項及其安全性含意的詳細資訊,請參閱 存取存放庫、成品和其他資源

      • 這種方法不會被簽出: git submodule add https://fabrikam-fiber@dev.azure.com/fabrikam-fiber/FabrikamFiberProject/_git/FabrikamFiber FabrikamFiber

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

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

如果您無法使用 Checkout 子模組 選項,則可以改為使用自訂腳本步驟來提取子模組。 首先, (PAT) 取得個人存取權杖,並在其前面加上 pat: 。 接下來,以 base64 編碼 這個前置字串來建立基本的驗證 token。 最後,將此腳本新增至您的管線:

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 認證管理員通常是不正確,因為認證管理員可能會在每次更新子模組時提示您重新輸入認證。 當您無法進行使用者互動時,不適合在自動化組建期間使用這種做法。

淺層提取

您可能會想要限制歷程記錄下載的距離。 實際上,這會導致 git fetch --depth=n 。 如果您的存放庫很大,此選項可能會讓您的組建管線更有效率。 如果您的存放庫長時間已在使用中,且具有相當大記錄,則您的儲存機制可能會很大。 如果您加入和更新的大型檔案,它也可能會很大。

您可以 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

在這些情況下,此選項可協助您節省網路和存放裝置資源。 也可以節省時間。 它不一定會節省時間,因為在某些情況下,伺服器可能需要花時間計算要下載的認可,以取得您指定的深度。

注意

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

不要同步來源

您可能會想要略過提取新的認可。 當您想要執行下列動作時,此選項會很有用:

  • 使用您自己的自訂選項的 Git init、config 和 fetch。

  • 使用組建管線來執行自動化 (例如,某些腳本) 不依賴版本控制中的程式碼。

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

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

注意

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

清除組建

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

一般而言,若要讓自我裝載代理程式的效能更快,請不要清除存放庫。 在此情況下,若要獲得最佳效能,請停用您正在建立的工作或工具的任何 清除 選項,以累加方式建立。

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

注意

如果您使用 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.RequestedFor) $(Build.DefinitionName) 可以包含空白字元。 如果值包含空白字元,則不會建立標記。

在您的組建管線標記來源之後,會自動將具有 Git ref 的成品 refs/tags/{tag} 新增至已完成的組建。 這可讓您的小組有額外的追蹤能力,以及更方便使用的方式,從組建流覽至所建立的程式碼。 標記會被視為組建成品,因為它是由組建所產生。 以手動方式或透過保留原則刪除組建時,也會一併刪除該標記。

預先定義的變數

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

  • Build.RequestedFor
  • Build.RequestedForId
  • Build.RequestedForEmail

狀態更新

有兩種類型的狀態,Azure Pipelines 回傳至 GitHub 基本狀態並 GitHub 檢查執行。 GitHub只有 GitHub Apps 可使用檢查功能。

管線狀態會顯示在 GitHub UI 中的不同位置。

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

PAT 或 OAuth GitHub 連接

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

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

GitHub檢查

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

針對使用 GitHub 應用程式的每個管線,會針對整體執行以及該執行中的每個工作回傳檢查。

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

GitHub 檢查重新執行

按一下檢查執行名稱旁邊的 [重新執行] 連結,會導致 Azure Pipelines 重試產生檢查執行的執行。 結果執行的執行數目將會相同,且會使用與初始組建相同的原始程式碼、設定和 YAML 檔案版本。 只有在初始執行和任何相依下游工作中失敗的工作,才會再次執行。 按一下 [重新執行所有失敗的檢查] 連結將會有相同的效果。 這與在 Azure Pipelines UI 中按一下 [重新嘗試執行] 的行為相同。 按一下 [重新執行所有檢查] 將會產生新的回合,其中包含新的執行編號,並會在設定或 YAML 檔中收取變更。

常見問題集

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

  • 連線類型 我不確定我要使用何種連線類型來將管線連接至 GitHub。
  • 失敗的觸發程式: 當我將更新推送至存放庫時,不會觸發我的管線。
  • 失敗簽出 正在觸發我的管線,但在結帳步驟中會失敗。
  • 錯誤的版本 我的管線會執行,但它會使用未預期的來源/YAML 版本。
  • 遺漏狀態更新 因為 Azure Pipelines 未報告狀態更新,所以會封鎖我的 GitHub pr。

連線類型

若要針對觸發程式進行疑難排解,如何知道我在管線中使用的 GitHub 連線類型?

針對觸發程式的問題進行疑難排解非常多,取決於您在管線中使用的 GitHub 連線類型。 有兩種方式可判斷連接的類型-從 GitHub 和 Azure Pipelines。

  • 從 GitHub:如果存放庫設定為使用 GitHub 應用程式,則 pr 和認可的狀態將會是 [執行檢查]。 如果存放庫已 Azure Pipelines 設定 OAuth 或 PAT 連線,則狀態會是「舊」狀態樣式。 若要判斷狀態為 [檢查執行] 或 [簡單] 狀態的快速方法,就是查看 GitHub PR 上的 [交談] 索引標籤。

    • 如果 [詳細資料] 連結重新導向至 [檢查] 索引標籤,則會執行檢查,而且存放庫會使用應用程式。
    • 如果 [詳細資料] 連結重新導向至 Azure DevOps 管線,則狀態會是「舊樣式」狀態,而存放庫不會使用應用程式。
  • 從 Azure Pipelines:您也可以在 Azure Pipelines UI 中檢查管線,以判斷連接的類型。 開啟管線的編輯器。 選取 [ 觸發 程式] 以開啟管線的傳統編輯器。 然後,選取 [ YAML ] 索引標籤,然後選取 [ 取得來源 ] 步驟。 您將會注意到 使用連接授權 的橫幅:指出用來整合管線與 GitHub 的服務連線。 服務連接的名稱是超連結。 選取它來流覽至服務連接屬性。 服務連接的屬性將會指出所使用的連線類型:

    • Azure Pipelines 應用程式 表示 GitHub 應用程式連接
    • oauth 表示 oauth 連接
    • personalaccesstoken 表示 PAT 驗證

如何? 將我的管線切換為使用 GitHub 應用程式而非 OAuth?

GitHub 和 Azure Pipelines 之間建議使用 GitHub 應用程式,而非 OAuth 或 PAT 連接。 若要切換至 GitHub 應用程式,請遵循下列步驟:

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

為什麼不會顯示 GitHub 存放庫讓我選擇 Azure Pipelines?

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

當我在建立管線期間選取存放庫時,出現錯誤「儲存機制 {存放庫-名稱} 與另一個 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 org 中的管線才能自動觸發。 若要變更對應,請從 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,您可能會在這裡看到錯誤。

  • GitHub Azure DevOps 的流量可能會受到節流。 當 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 觸發程式,會評估從提取來源和目標分支所產生的 YAML 檔案,以查看是否應該執行 PR 組建。

遺失狀態更新

因為 Azure Pipelines 未更新狀態,所以會封鎖 GitHub 中的 PR。

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