連線 Azure Boards 至 GitHub （雲端）

  • 發行項

Azure DevOps Services

針對您的軟體開發和 Azure Boards 專案使用 GitHub.com 存放庫來規劃和追蹤您的工作。 連線 您的專案和存放庫，讓您的 GitHub 認可和提取要求會連結到 Azure Boards 中的工作專案。

注意

Azure Boards 和 Azure DevOps Services 支援與 GitHub.com 和 GitHub Enterprise Server 存放庫的整合。 如果您想要從內部部署 Azure DevOps Server 連線，請參閱將 Azure DevOps Server 連線 至 GitHub Enterprise Server。

必要條件

  • 您必須有 Azure Boards 或 Azure DevOps 專案。 如果您還沒有專案， 請建立一個專案。
  • 您必須是 Project 管理員 istrators 群組的成員。 如果您已建立專案，則您具有許可權。
  • 您必須是 GitHub 存放庫的系統管理員或擁有者才能連線。 只要您是這些存放庫的系統管理員，您就可以連線到多個 GitHub 存放庫。

驗證選項

根據您想要連線的 GitHub 平臺，支援下列驗證選項。

GitHub.com

GitHub Enterprise Server

注意

如果您選擇將 Github 與 PAT 連線，請務必為 GitHub 帳戶上的 PAT 設定單一登錄 （SSO）。 這需要能夠取得已設定安全性聲明標記語言 （SAML） SSO 驗證的組織存放庫清單。

連線 Azure Boards 至 GitHub 存放庫。

  1. 登入您的 Azure DevOps 專案。

  2. 選取 [項目設定>][GitHub 連線]。

    Screenshot of open Project Settings>GitHub connections.

  3. 如果您是第一次從專案建立連線，請選擇 連線 GitHub 帳戶以使用 GitHub 帳戶認證。

    Screenshot of first time connecting with GitHub credentials.

    否則，請選擇 [新增連線]，然後從 [新增 連線] 對話框中選取您的驗證方法。

    當您使用 GitHub 帳戶進行連線時，請使用 GitHub 帳戶認證進行驗證。 若要使用 PAT，請參閱 使用 PAT 新增 GitHub 連線。 若要連線到 GitHub Enterprise Server，請參閱 在 GitHub 中將 Azure DevOps 註冊為 OAuth 應用程式。

使用 GitHub 認證新增 GitHub 連線

您最多可以將 500 個 GitHub 存放庫連線到 Azure Boards 專案。

  1. 如果您是第一次從 Azure Boards 連線到 GitHub，系統會要求您使用 GitHub 認證登入。 選擇您是存放庫管理員的帳戶。

  2. 選擇您要連線的 GitHub 帳戶或組織。 只會列出您擁有或為系統管理員的組織。

    如果組織的所有存放庫都已連線到 Azure Boards，您會看到下列訊息。

    Screenshot of message where no more repositories exist to connect.

  3. 輸入您的 GitHub 認證。 如果您已啟用雙因素驗證，請輸入 GitHub 傳送的驗證碼，然後選擇 [ 驗證]。 否則，系統會自動辨識您的 GitHub 組織，因為您的 GitHub 帳戶先前已與您的 Azure DevOps Services 帳戶相關聯。

選擇存放庫

驗證之後，您可以選取要連線的存放庫。

  1. [ 新增 GitHub 存放庫 ] 對話框會自動顯示並選取您為所選組織系統管理員的所有 GitHub.com 存放庫。 取消選取您不想參與整合的任何存放庫。

    Screenshot showing GitHub repos.

    提示

    我們建議您只將 GitHub 存放庫連線到單一 Azure DevOps 組織中定義的專案。 將相同的 GitHub 存放庫 連線 至兩個以上的 Azure DevOps 組織中定義的專案，可能會導致非預期AB# 提及連結。 如需詳細資訊，請參閱 針對 GitHub 和 Azure Boards 整合進行疑難解答。

    如果所有存放庫都已連線到目前或其他組織，則會顯示下列訊息。

    Screenshot of message where no more repositories exist to connect.

  2. 完成時，選取儲存。

確認連線

  1. 檢閱顯示的 GitHub 頁面，然後選擇 [ 核准]、[安裝] 和 [授權]。

    Screenshot showing confirming GitHub repositories.

  2. 提供您的 GitHub 密碼以確認。

  3. 完成時，您應該會看到已列出所選存放庫的新連線。

Screenshot of list of connected repositories.

若要變更設定或管理 GitHub 的 Azure Boards 應用程式，請參閱 變更 Azure Boards 的存放庫存取權。

使用 PAT 新增 GitHub 連線

建議您使用 GitHub 帳戶認證來連線到 GitHub 存放庫。 不過，如果您需要使用 PAT，請遵循這些程式來執行此動作。

提示

當您建立 GitHub PAT 時，請確定您包含下列範圍： repo, read:user, user:email, admin:repo_hook。

  1. 選擇 [個人存取令牌]。

    Screenshot of New GitHub connection dialog, choosing Personal Access Token.

    若要建立 GitHub PAT，請移至 GitHub 開發人員 設定 > 個人存取令牌。

  2. 輸入 PAT，然後選擇 [連線]。

    Screenshot showing entered PAT.

  3. 依照本文稍早選擇存放庫中所述 的程序，選擇您要連線至專案的存放庫 。

  4. 如果這是第一次從 Azure Boards 連線到 GitHub 帳戶或組織，您也必須安裝適用於 GitHub 的 Azure Boards 應用程式。 確認本文稍早的連線 。

在 GitHub 中將 Azure DevOps 註冊為 OAuth 應用程式

如果您打算使用 OAuth 將 Azure DevOps 與 GitHub Enterprise Server 連線，您必須先將應用程式註冊為 OAuth 應用程式。 如需詳細資訊，請參閱 建立 OAuth 應用程式。

註冊 Azure DevOps Services

  1. 登入 GitHub Enterprise 伺服器的入口網站。

    Screenshot of sign in for GitHub Enterprise server.

  2. 開啟 [設定> 開發人員設定>Oauth Apps>新增 OAuth 應用程式]。

    Screenshot showing sequence for New OAuth App.

  3. 輸入資訊以註冊您的應用程式。

    針對首頁 URL，指定組織的組織 URL。
    針對授權回 呼 URL，請使用下列模式來建構 URL。

    {Azure DevOps Services Organization URL}/_admin/oauth2/callback

    例如：

    https://dev.azure.com/fabrikam/_admin/oauth2/callback

    Screenshot showing app to register.

  4. 選取 [ 註冊應用程式]。

  5. 您已註冊 OAuth 應用程式的用戶端識別碼和用戶端密碼隨即出現。

    Screenshot of Client ID and Client Secret for the registered OAuth application.

在 Azure DevOps Services 中註冊 OAuth 組態

  1. 登入 Azure DevOps Services 的入口網站。

  2. 將 GitHub Enterprise Oauth 組態新增至您的組織。

  3. 在 [組織設定] 中，選取 [Oauth 組態>][新增 Oauth 組態]。

    Screenshot of Open Organization Settings, OAuth configurations.

  4. 輸入您的資訊，然後選取 [ 建立]。

    OAuth configurations dialog.

連線 Azure DevOps Services 至 GitHub Enterprise Server

重要

若要將 Azure DevOps Services 連線到您的 GitHub Enterprise Server，您的 GitHub Enterprise Server 必須能夠從因特網充分存取。 請確定 Azure DNS 可以解析 GitHub Enterprise 伺服器名稱，而防火牆允許從 Azure 資料中心 IP 位址進行存取。 若要判斷IP位址範圍，請參閱 Microsoft Azure 資料中心IP範圍。 線上問題存在時遇到的常見錯誤訊息如下：

無法解析遠端名稱：『github-enterprise-server.contoso.com』

如果您遇到此錯誤，請檢查您的伺服器是否可供存取。 如需詳細資訊，請參閱 Azure DNS 常見問題。

  1. 選取 [項目設定>][GitHub 連線>][GitHub Enterprise Server] 進行第一次連線。

    First connection, choose GitHub Enterprise Server.

    或者，從 [ 新增 GitHub 連線 ] 對話框，選取 [GitHub Enterprise Server]。

    Screenshot of New GitHub connection dialog, choose GitHub Enterprise Server.

  2. 選取驗證方法。

    Screenshot showing authentication method dialog.

    使用 OAuth 連線

    選擇您在 Azure DevOps Services 中註冊 OAuth 設定的步驟 4 中設定的設定，然後選擇 [連線]。

    Screenshot of New GitHub Enterprise connection, OAuth connection dialog.

    使用個人存取令牌 連線

    輸入 GitHub Enterprise 伺服器的 URL，以及該伺服器所辨識的個人存取令牌認證。 然後選擇 [連線]。

    Screenshot of New GitHub Enterprise connection, Personal access token connection dialog.

    使用使用者名稱和密碼 連線

    輸入 GitHub Enterprise 伺服器的 URL，以及該伺服器所辨識的系統管理員帳戶認證，然後選取 [連線]。

    Screenshot of New GitHub Enterprise connection screen, User Name connection dialog.

  3. 對話框會列出您擁有 GitHub 系統管理許可權的所有存放庫。 您可以在 Mine 和 All 之間切換，以判斷是否有其他項目出現，然後檢查您要新增的。 當完成時，選擇儲存。

    Screenshot of repositories listed.

    提示

    您只能連線到一個 GitHub 組織下定義的存放庫。 若要將項目連線至另一個 GitHub 組織中定義的其他存放庫，您必須新增另一個連線。

  4. 如果您是第一次從 Azure Boards 連線到 GitHub 帳戶或組織，您也會安裝適用於 GitHub 的 Azure Boards 應用程式。 確認本文稍早的連線 。

解決連線問題

Azure Boards-GitHub 整合依賴各種驗證通訊協議來支持連線。 變更使用者的許可權範圍或驗證認證，可能會導致撤銷連線至 Azure Boards 的 GitHub 存放庫。

如需適用於 GitHub 之 Azure Boards 應用程式支援的整合概觀，請參閱 Azure Boards-GitHub 整合。

支援的驗證選項

根據您想要連線的 GitHub 平臺，支援下列驗證選項。

平台

GitHub.com

GitHub Enterprise Server

Azure DevOps Services

  • GitHub.com 用戶帳戶
  • 個人存取權杖 (PAT)
  • OAuth
  • PAT
  • 用戶名稱加上密碼

Azure DevOps Server 2020

不適用

  • PAT
  • 用戶名稱加上密碼

Azure DevOps Server 2019

不適用

  • OAuth
  • PAT
  • 用戶名稱加上密碼

注意

使用適用於 GitHub 的 Azure Boards 應用程式，Azure Boards 和 Azure DevOps Services 支援與 GitHub.com 和 GitHub Enterprise Server 存放庫整合。 Azure DevOps Server 2019 和更新版本僅支援與 GitHub Enterprise Server 存放庫整合。不支援與其他 Git 存放庫整合。

授與 Azure Boards 組織存取權

如果 Azure Boards 與 GitHub 之間的整合未如預期般運作，請確認您已授與組織存取權。

  1. 從 GitHub 入口網站，從您的配置檔功能表開啟 設定。
    Screenshot of open profile, choose Settings.

  2. 選取 [整合>授權的 OAuth Apps>Azure Boards] 底下的 [應用程式]。

  3. 在 [組織存取權] 底下，解決可能出現的任何問題。 選取 [授 與] 以將存取權授與任何顯示為擱 置存取要求的組織。

    Screenshot of Organization access with organizations without access.

解決存取問題

當與 GitHub 的 Azure Boards 連線不再具有存取權時，它會在具有 red-X 的使用者介面中顯示警示狀態。 將滑鼠停留在警示上，指出認證不再有效。 若要更正問題，請移除連線並重新建立新的連線。

Screenshot of failed connection.

若要解決此問題，請考慮下列專案：

  • 如果連線使用 OAuth：

    • Azure Boards 應用程式已拒絕其中一個存放庫的存取權。

    • GitHub 可能無法使用/無法連線。 這可能是因為服務中斷或內部部署的基礎結構/網路問題。 您可以從下列連結檢查服務狀態：

      刪除並重新建立 GitHub 存放庫的連線。 此重新建立的聯機會導致 GitHub 提示您重新授權 Azure Boards。

  • 如果連線使用 PAT：

    • PAT 可能已撤銷，或必要的許可權範圍已變更且不足。

    • 使用者可能會在 GitHub 存放庫上遺失系統管理員許可權。

      重新建立 PAT，並確定令牌的範圍包含必要的許可權： repo, read:user, user:email, admin:repo_hook。

解決中斷的 GitHub Enterprise Server 連線

如果您已使用現有的 GitHub Enterprise Server 連線從 Azure DevOps Server 移轉至 Azure DevOps Services，現有的連線將無法如預期般運作。 GitHub 內提及的工作專案可能會延遲或永遠不會顯示在 Azure DevOps Services 中。 發生此問題的原因是與 GitHub 相關聯的回呼 URL 已不再有效。

請考慮下列解決方案：

  • 拿掉並重新建立連線：移除並重新建立 GitHub Enterprise Server 存放庫的連線。 請遵循 Azure Boards 檔中 連線 中提供的步驟順序。

  • 修正 Webhook URL：移至 GitHub 的存放庫設定頁面，並編輯 Webhook URL 以指出已移轉的 Azure DevOps Services 組織 URL： https://dev.azure.com/{OrganizationName}/_apis/work/events?api-version=5.2-preview

連線 至多個 Azure DevOps 組織

如果您將 GitHub 存放庫連線到多個 Azure DevOps 組織中定義的兩個或多個專案，例如 dev.azure.com/Contoso 和 dev.azure.com/Fabrikam，當您使用 AB# 提及連結至工作專案時，可能會取得非預期的結果。 發生此問題的原因是工作專案標識符在 Azure DevOps 組織中並不是唯一的，因此 AB#12 可以參考 Contoso 或 Fabrikam 組織中的工作專案。 因此，當認可訊息或提取要求中提及工作專案時，兩個組織都會嘗試建立具有相符標識符的工作項目連結（如果有的話）。

一般而言，使用者想要 AB# 提及連結至其中一個專案中的單一工作專案。 但是，如果這兩個帳戶中都有相同標識符的工作專案，則會為這兩個工作專案建立連結，這可能會導致混淆。

目前無法解決此問題，因此我們建議您只將單一 GitHub 存放庫連線到單一 Azure DevOps 組織。

注意

當您使用適用於 GitHub 的 Azure Boards 應用程式進行連線時，應用程式會防止您連線到兩個不同的組織。 如果 GitHub 存放庫錯誤地連線到錯誤的 Azure DevOps 組織，您必須先連絡該組織的擁有者以移除連線，才能將存放庫新增至正確的 Azure DevOps 組織。

更新選取工作項目類型的 XML 定義

如果您的組織使用託管的 XML 或內部部署 XML 程式模型來自定義工作追蹤體驗，而且您想要從工作專案表單的 [開發] 區段連結並檢視 GitHub 連結類型，您必須更新工作專案類型的 XML 定義。

例如，如果您想要將用戶劇本和 Bug 連結至 GitHub 認可，並從 [開發] 區段提取要求，您需要更新使用者劇本和 Bug 的 XML 定義。

請遵循裝載 XML 進程模型中提供的工作順序來更新 XML 定義。 針對每個工作專案類型，尋找 區 Group Label="Development" 段，並在下列程式代碼語法中新增下列兩行，以支援外部連結類型： GitHub Commit 和 GitHub 提取要求。

             <ExternalLinkFilter Type="GitHub Pull Request" />  
             <ExternalLinkFilter Type="GitHub Commit" />

更新時，區段應該會顯示如下。

<Group Label="Development">  
   <Control Type="LinksControl" Name="Development">  
      <LinksControlOptions ViewMode="Dynamic" ZeroDataExperience="Development" ShowCallToAction="true">  
         <ListViewOptions GroupLinks="false">   
         </ListViewOptions>  
         <LinkFilters>  
             <ExternalLinkFilter Type="Build" />  
             <ExternalLinkFilter Type="Integrated in build" />  
             <ExternalLinkFilter Type="Pull Request" />  
             <ExternalLinkFilter Type="Branch" />  
             <ExternalLinkFilter Type="Fixed in Commit" />  
             <ExternalLinkFilter Type="Fixed in Changeset" />  
             <ExternalLinkFilter Type="Source Code File" />  
             <ExternalLinkFilter Type="Found in build" />  
             <ExternalLinkFilter Type="GitHub Pull Request" />  
             <ExternalLinkFilter Type="GitHub Commit" />  
         </LinkFilters>  
      </LinksControlOptions>  
   </Control>  
</Group>

下一步

將 GitHub 認可和提取要求連結至工作專案