建立提取要求

Azure DevOps 服務 |Azure DevOps Server |Azure DevOps Server 2022 |Azure DevOps Server 2020

Visual Studio 2019 |Visual Studio 2022

建立提取要求 （PR），以變更、檢閱及合併 Git 存放庫中的程式代碼。 您可以從上游存放 庫中的分支 或存放庫分支建立PR。 您的小組可以 檢閱PR， 並提供變更的意見反應。 檢閱者可以逐步執行建議的變更、留下批注，以及投票以核准或拒絕PR。 根據 分支原則 和其他需求，您的 PR 可能需要符合各種準則，才能 完成 PR 並將變更合併至目標分支。

如需PR指導方針和管理考慮，請參閱 關於提取要求。

先決條件

類別	需求
存取層級	- 檢視或審查 PR：至少需有 基本存取權。 針對公用專案，用戶 項目關係人存取 權具有 Azure Repos 的完整存取權。
許可	- 參與 PR： 讀取者 安全組的成員或對應的許可權。 - 建立並完成一個 PR：屬於參與者安全組的成員或具備相應權限。
服務	啟用 Repos。
工具	Azure DevOps CLI。

如需許可權和存取的詳細資訊，請參閱 預設 Git 存放庫和分支許可權 和 關於存取層級。

建立提取要求

您可以從 Azure DevOps 專案網站、Visual Studio 或 Azure DevOps CLI 建立新的 PR。

瀏覽器

您可以從 Azure DevOps 專案網站建立新的 PR：

• 拉取請求頁面。
• 功能分支已推送至您的倉庫。
• 使用櫻桃挑選的現有PR。
• 已連結的 Azure Boards 工作專案中的開發控制項。

從提取要求頁面建立PR

您可以從您專案的 [ 提取要求 ] 頁面上，為任何分支建立 PR。

1. 在 [ Repos>提取要求 ] 頁面上，選取右上方 的 [新增提取要求 ]。

   

2. 選取具有變更的分支，以及您想要將變更合併到的分支，例如主要分支。

   

3. 輸入您的PR詳細數據 並建立PR。

從推送分支建立PR

推送或更新功能分支之後，Azure Repos 會顯示建立PR的提示。

• 在 [ 提取要求 ] 頁面上：

  

• 在 [檔案] 頁面上：

  

選取 建立拉取請求 以移至您可以 輸入 PR 詳細資料 並建立 PR 的頁面。

從連結的工作專案建立PR

您可以直接從連結至分支的 Azure Boards 工作專案建立 PR。

1. 在 Azure Boards 中，從 [工作] 檢視中的待辦專案或查詢，開啟連結至分支的工作專案。

2. 在工作專案的 [開發 ] 區域中，選取 [ 建立提取要求]。

   

此連結會帶您前往頁面，您可以在其中 輸入 PR 詳細數據 並建立 PR。

Visual Studio

若要建立提取要求：

1. 在 Git 功能表中，選取 [管理分支]。

2. 以滑鼠右鍵按兩下分支，然後選取 [ 建立提取要求]。

3. 視需要編輯來源和目標分支、輸入標題和選擇性描述，然後選取 [ 建立]。

Visual Studio 2019 16.8 版和更新版本提供 Git 版本控制體驗，同時維護 Team Explorer Git 使用者介面。 若要使用Team Explorer，請從功能表列取消勾選 工具>選項>預覽功能 中的 >新增 Git 使用者體驗。 您可以從任一個介面交替使用 Git 功能。

若要從 Visual Studio Team Explorer 建立 PR：

1. 從 Visual Studio 連線到您的專案。

2. 選取 檢視>Team Explorer 以開啟 Team Explorer。 您也可以按 Ctrl+\、+

3. 從 Home中，選取 [提取要求]，以檢視您開啟或指派給您的 PR 清單。

4. 從 [ 提取要求 ] 檢視中，選取 [新增提取要求]。

   

5. 選取來源和目標分支、輸入標題和選擇性描述，然後選取 [ 建立]。

   

6. 建立 PR 之後，選取 [ 在瀏覽器中開啟 ] 以在 Azure DevOps 入口網站中開啟新的 PR。

您也可以以滑鼠右鍵按兩下分支名稱，然後選取 [建立提取要求]，以從Team Explorer中的 [分支] 檢視建立PR。

Azure DevOps CLI

若要在您的專案中建立新的 PR，請使用 az repos pr create。 若要在建立之後於瀏覽器中開啟PR，請使用 --open 參數。

az repos pr create [--auto-complete {false, true}]
                   [--bypass-policy {false, true}]
                   [--bypass-policy-reason]
                   [--delete-source-branch {false, true}]
                   [--description]
                   [--detect {false, true}]
                   [--draft {false, true}]
                   [--merge-commit-message]
                   [--open]
                   [--org]
                   [--project]
                   [--repository]
                   [--reviewers]
                   [--source-branch]
                   [--squash {false, true}]
                   [--subscription]
                   [--target-branch]
                   [--title]
                   [--transition-work-items {false, true}]
                   [--work-items]

參數

參數	說明
--auto-complete	當所有策略通過後，將「拉取請求」設置為自動完成並合併到目標分支。 接受的值： false、 true。
--bypass-policy	略過任何必需的政策，一旦拉取請求可合併後即可完成。 接受的值： false、 true。
--bypass-policy-reason	略過必要原則的原因。
--delete-source-branch	提取要求完成並合併至目標分支之後，請刪除來源分支。 接受的值： false、 true。
--description -d	新合併請求的描述，可以包含 Markdown。 每個值都是新行。 例如： --description "First Line" "Second Line" 。
--detect	自動偵測企業組織。 接受的值： false、 true。
--draft	在草稿模式中建立提取要求，作為進行中的工作。 接受的值： false、 true。
--merge-commit-message	當您合併提交時所顯示的訊息。
--open	在網頁瀏覽器中開啟提取要求。
--org --organization	Azure DevOps 組織 URL。 您可以使用 az devops configure -d organization=ORG_URL 來設定預設組織。 如果未設定為預設值，或未透過 git config 抓取，則為必要項目。範例：https://dev.azure.com/MyOrganizationName/。
--project -p	項目的名稱或識別碼。 您可以使用 az devops configure -d project=NAME_OR_ID 來設定預設專案。 如果未設定為預設值或未經由 git config 自動設定，則此步驟為必需。
--repository -r	要用來建立提取要求之存放庫的名稱或標識碼。 必要的 參數。
--reviewers	其他使用者或群組將作為新拉取請求的檢閱者包含。 以空格分隔。
--source-branch -s	來源分支的名稱。 範例： "dev".
--squash	在合併至目標分支時，將來源分支中的提交壓縮。 接受的值： false、 true。
--subscription	Azure 訂用帳戶的名稱或標識碼。 您可以使用 az account set -s NAME_OR_ID 來設定預設的訂閱帳戶。
--target-branch -t	目標分支的名稱。 如果未指定，則會預設為目標存放庫的預設分支。
--title	新提取要求的標題。
--transition-work-items	當 PR 變更狀態時，將連結至 PR 的任何工作項目轉換為下一個邏輯狀態。 例如，將作用中工作項目更改為 [已解決]。 接受的值： false、 true。
--work-items	要連結至新拉取請求的工作項目識別碼。 以空格分隔。

範例

下列命令會從 new 分支建立一個拉取要求 (PR) 到 Fabrikam 存放庫的預設 main 分支，並在瀏覽器中開啟此拉取要求，同時在表格中顯示命令的輸出結果。 此範例使用預設組態： az devops configure --defaults organization=https://dev.azure.com/fabrikamprime project="Fabrikam Fiber"。

az repos pr create --repository Fabrikam --source-branch new --open --output table

ID    Created     Creator              Title                         Status    IsDraft    Repository
----  ----------  -------------------  ----------------------------  --------  ---------  ------------
30    2021-10-31  jamalh@fabrikam.com  Updated note-new-git-tool.md  Active    False      Fabrikam

您可以在 PR 建立時或之後新增許多其他 PR 詳細數據。 若要將詳細數據、檢閱者、工作專案和完成選項新增至PR，請參閱 新增詳細資料或編輯PR。

使用精選操作新增更新

您可以使用 cherry-pick 將提交從一個分支複製到另一個分支。 不同於合併或重新基底，擷取只會從您選擇的提交中獲取變更，而不是分支中的所有變更。

若要從已完成的 PR 中挑選變更，請在 PR 的 [概觀] 頁面上選取 [挑選]。 若要從作用中的 PR 複製變更，請從 PR 的「更多選項」選單中選取「Cherry-pick」。 此動作會建立包含複製變更的新分支。 然後，您可以從新的分支建立新的 PR。 如需詳細指示，請參閱 使用 cherry-pick 複製變更。

切換提取要求的來源和目標分支

第一次儲存PR之前，您可以選取分支名稱旁的 [ 切換來源和目標分支 ] 圖示，以切換PR的來源和目標分支。 一旦 PR 處於作用中狀態，此圖示就會消失，但您仍然可以 變更 PR 的目標分支 。

使用提取要求範本

拉取請求範本是一個檔案，包含 Markdown 格式的文字，用於在您建立拉取請求時填入請求描述。 良好的PR描述會告知PR檢閱者預期什麼，並可協助追蹤工作，例如新增單元測試和更新檔。 您的小組可以建立預設 PR 範本，將文字新增至存放庫中所有新的 PR 描述。 此外，您可以從分支特定範本或其他小組定義的範本中選取。 如需建立和使用PR範本的詳細資訊，請參閱 使用範本改善提取要求描述。

如果您的存放庫有預設範本，則存放庫中的所有PR在建立時都會有預設範本的描述文字。 若要新增其他範本，請選取 [ 新增範本 ]，然後從下拉式清單中選擇範本。 您可以在描述中編輯範本文字、移除範本文字，或新增其他文字。

建立草稿 PR

如果您的 PR 尚未準備好進行檢閱，您可以建立草稿 PR 來表示正在進行的工作。 當 PR 準備好進行審核時，您可以發佈它，然後開始或繼續完整審核流程。

草稿 PR 與已發佈的 PR 有下列差異：

• 建置驗證原則不會自動執行。 您可以在 PR 中選擇 [更多選項] 功能表，以手動將組建驗證排入佇列。

• 在草稿模式中，投票會停用。

• 不會自動新增必要的檢閱者。 通知只會傳送給您明確新增至草稿 PR 的檢閱者。

• 草稿 PR 會顯示在具有 草稿 徽章的 PR 清單中。

  

瀏覽器

若要建立草稿 PR，請選取 [ 建立 ] 旁的箭號，然後在建立 PR 時選取 [ 建立為草稿 ]。 您不需要使用 標題前置詞，例如 WIP 或 DO NOT MERGE。

當您準備好檢閱並完成PR時，請選取PR右上角的發佈。 發佈PR會指派必要的檢閱者、評估原則，以及開始投票。

若要將現有的已發佈PR變更為草稿，請選擇 [標示為草稿]。 將PR標示為草稿會移除所有現有的投票。

Visual Studio

若要將 PR 設定為草稿，請開啟 PR，然後選取 [標示為草稿]。

• 若要從 Visual Studio 開啟提取要求，請在 Git 功能表中選取 <您的 Git 服務>>檢視提取要求，然後選取提取要求以開啟它。
• 若要從 Visual Studio Team Explorer 開啟提取要求，請從 [ 提取要求 ] 檢視中，以滑鼠右鍵按兩下 PR，然後選取 [在瀏覽器中開啟]。

Azure DevOps CLI

若要將 PR 建立為草稿，請在建立 PR 時將 --draft 參數設定為 true。 （需要 Azure DevOps Server 2020 或更新版本。

例如：

az repos pr create --repository Fabrikam --source-branch new --draft true

若要將現有的 PR 設定為草稿， 請使用 az repos pr update --id <PR Id> --draft true。

若要從 PR 移除草稿狀態，請將 設定 --draft 為 false。

新增或編輯提取要求標題和描述

瀏覽器

在 [ 新增提取要求 ] 頁面上，輸入 變更的標題 和詳細 描述 ，讓其他人可以看到變更所解決的問題。 在新的拉取請求中，就像在現有的拉取請求中一樣，您可以在不同的索引標籤中看到拉取請求中的檔案和提交。 您可以新增檢閱者、連結工作專案，以及將標籤新增至PR。

當您準備好檢閱變更時，請選取 [ 建立 ] 以建立PR。

如果您建立PR時尚未準備好所有工作專案、檢閱者或詳細數據，請不要擔心。 建立PR之後，您可以新增或更新這些專案。

編輯PR標題和描述

讓PR標題和描述保持在最新狀態，讓檢閱者可以瞭解PR中的變更。

您可以選取目前的標題，修改文字，以更新現有的 PR 標題。 選取 [ 儲存 ] 圖示以儲存變更，或選取 [復原] 圖示以捨棄變更。

選取編輯圖示在描述區段中，以編輯 PR 描述。

Visual Studio

當您在 Visual Studio 中建立 PR 時，請輸入變更的標題和詳細描述，讓其他人可以看到變更所解決的問題。 讓這些欄位保持在最新狀態，讓檢閱者可以瞭解PR中的變更。

若要編輯現有PR中的標題、描述或任何其他詳細數據，請在瀏覽器中開啟PR。

Azure DevOps CLI

您可以使用 az repos pr create 在 PR 建立期間新增詳細數據，或使用 az repos pr update 更新現有 PR 中的詳細數據。

當您使用 az repos pr create 建立 PR 時，請加入 --title 和您變更內容的詳細 --description，這樣其他人就可以看到變更所解決的問題。 參數 --description 會接受 Markdown 條目，而且自變數中的每個值都是 PR 描述中的一行新文字。

例如：

az repos pr create --repository Fabrikam --source-branch new --title "Update the readme" --description "This PR updates the readme." "These are *new* changes."

讓這些欄位保持在最新狀態，讓檢閱者可以瞭解PR中的變更。 若要更新 PR 的細節，請使用 az repos pr update 並搭配必要的 PR --id 參數。

例如，若要更新PR #21的標題和描述，請使用：

az repos pr update --id 21 --description "These updates are *no longer new*." --title "Old updates"

將檢閱者新增至提取要求

瀏覽器

您可以在新的或現有的 PR 的 [ 檢閱者 ] 區段中新增檢閱者。 您也可以將選擇性檢閱者變更為必要檢閱者、將必要的檢閱者變更為選擇性檢閱者，或將其移除，除非原則需要這些檢閱者。

分支策略 可能需要最少的檢閱者數目，或自動在 PR 中包含特定選擇性或必需的檢閱者。 您無法移除分支原則所需的檢閱者，但您可以將選擇性檢閱者變更為必要檢閱者或將其移除。

若要查看自動新增檢閱者的分支原則，請在PR總覽頁面的 [檢閱者] 區段中，以滑鼠右鍵單擊檢閱者旁的 [更多選項]。

如果您想要檢閱PR的使用者或群組不是您的項目成員，請先將它們 新增至專案， 然後才能將它們新增為檢閱者。

若要將檢閱者新增至新的PR，請執行下列步驟：

1. 在 [ 新增提取要求 ] 頁面上的 [ 檢閱者] 底下，選取 [ 搜尋使用者和群組] 以新增為檢閱者。
2. 當您輸入名稱或電子郵件位址時，下拉式清單會顯示相符的使用者和群組清單。 從清單中選取要新增為選擇性檢閱者的名稱。
3. 若要新增必要的檢閱者，請選取 [ 新增必要的檢閱者]，然後選取 [ 搜尋] 以新增必要的檢閱者 來搜尋並選取名稱。

若要將檢閱者新增至現有的PR，請執行下列步驟：

1. 在 [概觀] 頁面的 [檢閱者] 區段中，選取 [新增]，然後選取 [必要檢閱者] 或 [選擇性檢閱者]。

   

2. 當您輸入名稱或電子郵件位址時，會出現相符的使用者或群組清單。 選取要新增為檢閱者的名稱。

   

若要在必要和選擇性之間變更檢閱者，或移除檢閱者，請選取檢閱者名稱右邊的 [ 更多選項 ][⋮]。 若要檢視指定為檢閱者之群組或小組的成員資格，請選取群組的圖示。

Visual Studio

若要新增檢閱者，請在瀏覽器中開啟 PR，然後在 PR 的 [概 觀 ] 頁面上進行更新。

Azure DevOps CLI

您可以在創建時將可選的審查者添加到 PR 中
az repos pr create --reviewer "<Reviewer Name>" "<Another Reviewer>"。

例如：

az repos pr create --repository Fabrikam --source-branch new --reviewer "[Fabrikam]\Fabrikam Team" "[Fabrikam Fiber]\Web"

若要新增必要的檢閱者，或變更選擇性與必要之間的檢閱者，請在瀏覽器中開啟並更新PR。

若要管理現有 PR 的檢閱者，請使用 az repos pr reviewer。

• 若要將檢閱者新增至現有的PR，請使用
  az repos pr reviewer add --id <PR Id> --reviewer "<Reviewer Name>" "<Another Reviewer>"。
• 若要列出 PR 的檢閱者，請使用 az repos pr reviewer list --id <PR Id>。
• 若要從 PR 移除檢閱者，請使用 az repos pr reviewer remove --id <PR Id> --reviewer "<Reviewer Name>"。

az repos pr reviewer add --id
                         --reviewers
                         [--detect {false, true}]
                         [--org]
                         [--subscription]

參數

參數	說明
--id	拉取請求的識別碼。 必要。
--reviewers	要包含在拉取請求中作為檢閱者的使用者或群組。 以空格分隔。 必要。
--detect	自動偵測企業組織。 接受的值： false、 true。
--org --organization	Azure DevOps 組織 URL。 您可以使用 az devops configure -d organization=<ORG_URL> 來設定預設組織。 如果未設定為預設值或未通過 git config 取得，則為必要。範例：https://dev.azure.com/MyOrganizationName/。
--subscription	Azure 訂用帳戶的名稱或標識碼。 您可以使用 az account set -s <NAME_OR_ID> 來設定預設的訂閱帳戶。

將工作項目連結至提取要求

瀏覽器

若要將工作項目連結至新的PR，請執行下列步驟：

1. 在 [ 新增提取要求 ] 頁面上，於 [要連結的工作專案] 下，選取 [ 依標識符或標題搜尋工作專案]。
2. 開始輸入工作專案標識碼或標題，然後從出現的下拉式清單中選取要連結的工作專案。
   • 依標題搜尋會傳回依狀態篩選的工作專案;排除所有狀態為 已完成 和 移除 的工作專案。
   • 這些工作專案也會依日期和用戶進行篩選，只顯示過去 30 天內建立或更新的專案。 他們應該被目前使用者建立、指派或授權。

若要將工作項目連結至現有的PR，請執行下列步驟：

1. 在 [PR 概觀] 索引標籤的 [ 工作專案] 區域中，選取 +。

   

2. 輸入工作專案的標識碼，或搜尋工作項目標題。 從出現的清單中選取工作專案。

選取工作專案旁邊的 x 圖示，以移除工作項目連結。 拿掉連結只會移除工作專案與 PR 之間的連結。 在分支或提交中建立的連結會保留在工作項目中。

Visual Studio

若要連結工作專案，請在瀏覽器中開啟PR，然後在PR的[概 觀 ] 頁面上進行更新。

Azure DevOps CLI

您可以在建立 PR 時使用 az repos pr create --work-items <Id1> <Id2> 將 Azure Boards 工作項目連結至 PR，其中 <Id> 是工作項目的識別碼。

例如，下列命令會將工作專案 #63 和 #64 連結到 new 分支上的新 PR：

az repos pr create --repository Fabrikam --source-branch new --work-items 63 64

若要管理現有 PR 的工作專案，請使用 az repos pr work-item。

• 若要將工作項目連結至現有的PR，請使用 az repos pr work-item add --id <PR Id> --work-items <Id1> <Id2>。
• 若要列出連結至 PR 的工作項目，請使用 az repos pr work-item list --id <PR Id>。
• 若要從 PR 取消連結工作專案，請使用 az repos pr work-item remove --id <PR Id> --work-items <Id1>。 取消連結只會移除工作專案與 PR 之間的連結。 在分支或提交中建立的連結會保留在工作項目中。

az repos pr work-item add --id
                          --work-items
                          [--detect {false, true}]
                          [--org]
                          [--subscription]

參數

參數	說明
--id	拉取請求的識別碼。 必要。
--work-items	要連結之工作項目的識別碼。 以空格分隔。 必要。
--detect	自動偵測企業組織。 接受的值： false、 true。
--org --organization	Azure DevOps 組織 URL。 您可以使用 az devops configure -d organization=<ORG_URL> 來設定預設組織。 如果未設定為預設值或未通過 git config 取得，則為必要。範例：https://dev.azure.com/MyOrganizationName/。
--subscription	Azure 訂用帳戶的名稱或標識碼。 您可以使用 az account set -s <NAME_OR_ID> 來設定預設的訂閱帳戶。

將標籤新增至提取要求

使用標籤來顯示重要詳細數據，並協助組織PR。 卷標可以將額外的資訊傳達給檢閱者，例如 PR 仍在進行的工作，或是即將發行的緊急修補。

若要在建立PR時新增標籤，請在 [ 標記 ] 區段中輸入標籤名稱。 建立 PR 之後，您可以在 標籤 區段中管理標籤。

將附件新增至提取要求

您可以在創建 PR 時或之後，附加檔案，包括圖像。 選取 [ 描述 ] 欄位下方的剪紙圖示，或直接將檔案拖放到 PR 的 [描述 ] 欄位中。

變更活動拉取請求的目標分支

對於大多數小組，幾乎所有的 PR 都會以預設分支為目標，例如 main 或 develop。 如果您有時需要以不同的分支為目標，當您建立PR時，很容易忘記變更目標分支。 如果發生這種情況，您可以變更正在使用的 PR 的目標分支：

1. 在 [PR 概觀] 頁面右上方選取 [更多動作]，然後從下拉功能表中選取 [變更目標分支]。
2. 在 [ 變更目標分支 ] 窗格中，選取 [ 選擇目標分支]，選取新的分支，然後選取 [ 變更]。

將電子郵件提取要求通知傳送給項目關係人

您可以透過電子郵件共用提取要求，以通知檢閱者並與小組成員通訊。 若要共享 PR：

1. 在 PR 概觀 頁面上選取 更多選項，然後選取 分享拉取請求。

   

2. 在 [ 共用提取要求 ] 畫面上，在 [收件者 ： ] 字段中輸入其名稱，然後從出現的使用者名稱中選取，以新增收件者。 您也可以移除收件者。

3. 在 [ 附注][選擇性] 字段中新增選擇性訊息，然後選取 [ 傳送]。 收件者會收到一封電子郵件，要求他們注意並連結到 PR。

備註

使用內建電子郵件功能時，您只能將電子郵件傳送給個別項目成員的位址。 不支援將團隊群組或安全群組新增至 至： 行。 如果您新增無法辨識的電子郵件位址，您會收到訊息，指出一或多個收件者無權讀取已傳送的提取要求。

後續步驟

檢閱提取要求

相關文章

• 檢視提取要求
• 檢閱提取要求
• 完成拉取請求
• 變更預設分支
• 使用 cherry-pick 複製變更
• 瞭解提取要求和許可權