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

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

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

整合至 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使用圖示向使用者顯示 （綠色複選、紅色 X 代表 succeededfailed、時鐘為 pending和 紅色 ！ for error）。
• 會顯示 description 在圖示旁邊，且 context 可在工具提示中使用 。
• targetUrl套用 時，描述會轉譯為URL的連結。

更新狀態

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

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

反覆項目狀態

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

注意

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

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

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

請參閱 REST API 範例，以在反覆專案和提取要求上張貼狀態。

狀態原則

單獨使用狀態，即可將外部服務的詳細數據提供給 PR 體驗內的使用者。 有時候，共用PR的相關信息是必要的，但在其他情況下，應該封鎖PR合併，直到符合需求為止。 如同現成的原則， 狀態 原則提供外部服務封鎖PR完成的方式，直到符合需求為止。 如果需要原則，則必須傳遞才能完成提取要求。 如果原則是選擇性的，則只會提供參考性，而且不需要 的狀態 succeeded 才能完成提取要求。

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

指定狀態原則時，它必須有符合context所選名稱的狀態succeeded，才能傳遞此原則。

您也可以選取 [已授權的帳戶]，要求特定帳戶具有發佈將核准原則狀態的授權單位。

原則適用性

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

1. 默認 套用 - 原則會在建立提取要求時立即套用。 使用此選項時，在發佈狀態之前 succeeded ，原則不會在提取要求建立之後通過。 PR 可以藉由張貼 狀態 notApplicable來標示為豁免原則，這會移除原則需求。

2. 條件 式 - 在將第一個狀態張貼至提取要求之前，原則不會套用。

這些選項可用來建立一套動態原則。 在評估適用原則時，可能會將最上層「協調流程」原則設定為依預設套用。 然後，當其他條件式原則決定套用時（或許根據特定的組建輸出），狀態可以張貼，使其成為必要條件。 此協調流程原則可能會在評估完成時標示succeedednotApplicable，或標示為向PR指出原則不適用。

自訂動作

除了可觸發服務以更新PR狀態的預先定義服務攔截事件之外，您也可以使用 Azure DevOps Services 擴充 功能來擴充狀態功能表，為終端使用者提供觸發程式動作。 例如，如果 status 對應至使用者可重新啟動的測試回合，則可以將 [重新啟動 ] 功能表項移至將觸發測試執行的狀態功能表。 若要新增狀態功能表，您必須使用 貢獻模型。 如需詳細資訊，請參閱 Azure DevOps 擴充功能範例。

下一步

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

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