使用提取要求狀態自定義和擴充提取要求工作流程

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

提取要求 是協助程式代碼檢閱和管理存放庫內程式代碼移動的絕佳工具。 分支策略 透過建立每個程式碼變更必須執行的要求，在拉取請求過程中強制維持程式碼品質。 這些原則可讓小組強制執行許多與檢閱程式代碼和執行自動化組建相關的最佳做法，但許多小組有額外的需求和驗證，以在程式碼上執行。 為了涵蓋這些個別和自定義需求，Azure Repos 提供提取要求狀態。 拉取請求的狀態會整合到 PR 工作流程中，並允許外部服務以程式化方式將簡單的成功/失敗類型資訊與拉取請求關聯以核准程式代碼的更改。 您可以選擇性地封鎖提取要求，直到外部服務核准變更為止。

先決條件

類別	需求
專案存取	專案的成員。
許可	- 在私人項目中檢視程式碼：至少 基本 權限。 - 複製或貢獻私人專案中的程式碼：作為 貢獻者 安全群組的成員或在專案中具有相應的許可權。 - 設定分支或存放庫許可權：管理分支或存放庫的許可權 許可權。 - 變更預設分支：編輯原則 存放庫的許可權。 - 匯入存放庫：專案管理員成員 安全組或 Git 專案層級 建立存放庫 許可權設定為 允許。 如需詳細資訊，請參閱 設定 Git 存放庫許可權。
服務	啟用 Repos。
工具	選擇性。 使用 az repos 命令：Azure DevOps CLI。

備註

在公用專案中，具有 項目關係人 存取權的使用者具有 Azure Repos 的完整存取權，包括檢視、複製及參與程式代碼。

整合至 PR 工作流程包含一些不同的概念：

• 提取要求狀態 - 提供一種方式，讓服務將成功/失敗資訊與提取要求產生關聯。
• 狀態原則 - 提供一種機制來封鎖拉取請求的完成，直到拉取請求的狀態顯示成功為止。
• 自定義動作 - 提供一種使用 Azure DevOps Services 擴充功能來延伸狀態功能表的方法。

在本主題中，您將瞭解提取要求狀態，以及如何在PR工作流程中整合。

提取要求狀態

拉取請求狀態提供了一種方法，讓服務使用 狀態 API，將簡單的成功/失敗類型資訊與拉取請求產生關聯。 狀態包含四個主要資料片段：

• 狀態。 下列其中一個預先定義的狀態：succeeded、failed、pending、notSet、notApplicable或 error。
• 描述。 字串，描述用戶的狀態。
• [內容]。 狀態的名稱 - 通常描述張貼狀態的實體。
• URL。 用戶可以取得狀態特定詳細信息的連結。

基本上，狀態是使用者或服務發佈他們對拉取請求評估的方式，並提供問題的答案，例如：

• 變更是否符合需求？
• 我可以在哪裡深入瞭解我需要做什麼才能符合需求？

讓我們看看下列範例。 請考慮建置專案中所有程式碼變更所需的 CI 服務。 當該服務評估提取要求中的變更時，它必須回傳組建和測試結果。 對於通過建置的變更，可能會在 PR 上發佈如下所示的狀態：

{
    "state": "succeeded",
    "description": "CI build succeeded",
    "context": {
        "name": "my-ci-system",
        "genre": "continuous-integration"
    },
    "targetUrl": "http://contoso.com/CI/builds/1"
}

此狀態會顯示給 PR 詳情檢視中的最終使用者：

• state 會使用圖示顯示給使用者（succeeded用綠色勾，failed用紅色叉，pending用時鐘，以及 error用紅色驚嘆號）。
• 圖示旁會顯示 description，而 context 則會顯示在工具提示中。
• 套用 targetUrl 時，描述會轉譯為 URL 的連結。

更新狀態

服務可以透過發布其他狀態來更新單一 PR 的狀態，但只會顯示每個唯一 context的最新狀態。 張貼多個狀態可協助使用者管理預期。 例如，張貼 pending 狀態是向使用者確認系統已收到事件且正在啟動工作的好方法。 使用資訊 description，例如下列範例，可進一步協助使用者了解系統的運作方式：

• 「組建已排入佇列」
• 建置中
• 「建置成功」

迭代狀態

當 PR 中的來源分支更改時，會建立新的「迭代」來追蹤最新的變更。 評估程式代碼變更的服務會想要在PR的每個反覆專案上張貼新的狀態。 將狀態發佈到 PR 的特定迭代，可確保狀態僅適用於已評估的代碼，且不會影響未來的更新。

備註

如果所建立的 PR 包含超過 100,000 個修改過的檔案，則基於效能和穩定性考慮，該 PR 不支援反覆專案。 這表示會包含對這類PR的任何額外變更，但不會針對該變更建立任何新的反覆專案。 此外，任何建立不存在的迭代狀態的嘗試都會返回錯誤。

相反地，如果張貼的狀態適用於整個 PR，與程式代碼無關，則將其張貼至迭代可能是不必要的。 例如，檢查作者（不可變的PR屬性）是否屬於特定群組，只需要評估一次，而且不需要反覆項目狀態。

設定狀態原則時，如果使用反覆項目狀態，重設條件 應設定為 每當有新的變更時重設狀態。 這進一步保證了在最新版本的狀態為 succeeded之前，PR 無法被合併。

請參閱 REST API 範例，以在迭代 上張貼狀態，以及在提取請求 上張貼狀態。

狀態原則

只憑狀態，即可將來源於外部服務的詳細資訊提供給 PR 體驗中的使用者。 有時候，分享PR的資訊是必要的，但在其他情況下，應該阻止PR合併，直到滿足需求。 如同內建原則，狀態原則 提供外部服務封鎖PR完成的方式，直到符合需求為止。 如果需要政策，則必須通過才能完成拉取請求。 如果政策是選擇性的，那麼它僅供參考，並且不需要 succeeded 的狀態即可完成拉取請求。

狀態原則的設定方式就像其他 分支原則一樣，。 新增狀態原則時，必須輸入狀態原則的 名稱 和 類型。 如果先前已張貼過該狀態，您可以從清單中挑選它；如果是新的政策，您可以使用格式 /名稱輸入政策的名稱。

指定狀態原則時，必須存在 succeeded 狀態，且 context 符合所選名稱，此原則才能生效。

您也可以選取 授權的帳戶，以便要求特定帳戶發佈狀態，授權其批准政策。

原則適用性

原則適用性 選項會判斷此原則會在建立提取要求后立即套用，或原則是否只在第一個狀態張貼至提取要求之後才會套用。

1. 預設為自動套用 - 政策會在建立拉取請求時立即套用。 使用此選項時，策略在拉取請求建立後不會通過，直到張貼 succeeded 狀態為止。 PR 可以藉由設定狀態為 notApplicable來標示為免除該政策，這會移除政策需求。

2. 條件式 - 在將第一個狀態張貼至拉取請求之前，政策不會套用。

這些選項可用來建立一套動態原則。 在評估適用原則時，可能會將最上層「協調流程」原則設定為依預設套用。 然後，當其他條件政策被確定要套用時（可能根據特定的組建輸出），可以發佈狀態以使其成為必須的要求。 此協調流程原則可能會在評估完成時標示為 succeeded，也可以標示為 notApplicable，以向PR指出該原則不適用。

自訂動作

除了可觸發服務以更新拉取請求（PR）狀態的預先定義服務掛接事件之外，還可以使用 Azure DevOps Services 擴充功能來擴展狀態菜單， 為終端使用者提供觸發操作動作。 例如，如果 status 對應到使用者可重新啟動的測試回合，則可以在狀態功能表中加入 [重新啟動] 功能表項，用以觸發測試執行。 若要新增狀態選單，您必須使用 貢獻模型。 如需詳細資訊，請參閱 Azure DevOps 擴充功能範例。

後續步驟

深入瞭解 PR 狀態 API，並查看操作指南：

• 使用 Node.js 建立提取要求狀態伺服器
• 使用 Azure Functions 來建立自訂分支原則
• 設定外部服務的分支策略