将 Azure Boards 连接到 GitHub（云）

项目
05/13/2024

Azure DevOps Services

使用 GitHub.com 存储库进行软件开发，使用 Azure Boards 项目计划和跟踪工作。连接项目和存储库，以将 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 项目。如果没有项目，请创建一个。
你必须是项目管理员组的成员。如果你创建了项目，则拥有权限。
你必须是要连接到的 GitHub 存储库的管理员或所有者。只要你是多个存储库的管理员，就可以连接到多个 GitHub 存储库。

身份验证选项

根据你要连接到的 GitHub 平台，支持以下身份验证选项。

GitHub.com

GitHub Enterprise Server

GitHub.com 用户帐户（推荐）
个人访问令牌 (PAT)

OAuth（首选，需要注册）
PAT
用户名加密码

注意

如果选择使用 PAT 连接 Github，请确保在 GitHub 帐户上为 PAT 配置单一登录 (SSO)。如此才能获取配置了安全断言标记语言 (SAML) SSO 身份验证的组织的存储库列表。

将 Azure Boards 连接到 GitHub 存储库。

登录到 Azure DevOps 项目。
选择“项目设置”>“GitHub 连接”。
如果是首次从项目建立连接，请选择“连接 GitHub 帐户”以使用 GitHub 帐户凭证。

否则，请选择 新建连接，然后从新建连接对话框中选择身份验证方法。

使用 GitHub 帐户进行连接时，请使用 GitHub 帐户凭据进行身份验证。要使用 PAT，请参阅使用 PAT 添加 GitHub 连接。要连接到 GitHub Enterprise Server，请参阅在 GitHub 中将 Azure DevOps 注册为 OAuth 应用。

使用 GitHub 凭据添加 GitHub 连接

可将多达 500 个 GitHub 存储库连接到一个 Azure Boards 项目。

如果是首次从 Azure Boards 连接到 GitHub，系统会要求你使用 GitHub 凭证登录。选择你作为存储库管理员的帐户。
选择要连接的 GitHub 帐户或组织。仅列出了你拥有的或作为其管理员的组织。

如果组织的所有存储库均已连接到 Azure Boards，则会看到以下消息。
输入 GitHub 凭证。如果你已启用双因素身份验证，请输入 GitHub 发送给你的验证码，然后选择“验证”。否则，系统会自动识别你的 GitHub 组织，因为你的 GitHub 帐户已与你的 Azure DevOps Services 帐户相关联。

选择存储库

经过身份验证后，便可选择要连接的存储库。

添加 GitHub 存储库对话框会自动显示并选择你是所选组织管理员的所有 GitHub.com 存储库。取消选择不想参与集成的任何存储库。

提示

建议只将 GitHub 存储库连接到在单个 Azure DevOps 组织中定义的项目。将同一 GitHub 存储库连接到两个或多个 Azure DevOps 组织中定义的项目可能会导致意外的 AB# 提及链接。有关详细信息，请参阅 GitHub 与 Azure Boards 集成疑难解答。

如果所有存储库都已连接到当前组织或其他组织，则显示以下消息。
完成后，选择保存。

确认连接

查看显示的 GitHub 页面，然后选择批准、安装和授权。
提供 GitHub 密码进行确认。
完成后，应会看到列出与所选存储库建立的新连接。

已连接存储库的列表的屏幕截图。

若要更改配置或管理适用于 GitHub 的 Azure Boards 应用，请参阅更改对 Azure Boards 的存储库访问权限。

使用 PAT 添加 GitHub 连接

建议使用 GitHub 帐户凭据连接到 GitHub 存储库。但是，如果需要使用 PAT，请遵循以下过程。

提示

创建 GitHub PAT 时，请确保包含以下范围：repo, read:user, user:email, admin:repo_hook。

选择“个人访问令牌”。

要创建 GitHub PAT，请转到 GitHub 开发人员设置 > 个人访问令牌。
输入 PAT 并选择连接。
按照本文前面的选择存储库中概述的过程，选择要连接到项目的存储库。
如果是首次从 Azure Boards 连接到 GitHub 帐户或组织，则还必须安装适用于 GitHub 的 Azure Boards 应用。确认本文前述的连接。

在 GitHub 中将 Azure DevOps 注册为 OAuth 应用

如果计划使用 OAuth 将 Azure DevOps 与 GitHub Enterprise Server 连接，则首先需要将应用程序注册为 OAuth 应用。有关详细信息，请参阅创建 OAuth 应用。

注册 Azure DevOps Services

登录到 GitHub Enterprise Server 的 Web 门户。
打开“设置”>“开发人员设置”>“Oauth 应用”>“新建 OAuth 应用”。
输入注册信息。

对于主页 URL，请指定组织的组织 URL。
对于授权回调 URL，请使用以下模式构造 URL。

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

例如：

https://dev.azure.com/fabrikam/_admin/oauth2/callback
选择注册应用程序。
将显示已注册的 OAuth 应用程序的“客户端 ID”和“客户端密码”。

在 Azure DevOps Services 中注册 OAuth 配置

登录到 Azure DevOps Services 的 Web 门户。
将 GitHub Enterprise OAuth 配置添加到组织。
在“组织设置”中，选择“Oauth 配置”>“添加 Oauth 配置”。
输入你的信息，然后选择“创建”。

将 Azure DevOps Services 连接到 GitHub Enterprise Server

重要

若要将 Azure DevOps Services 连接到 GitHub Enterprise Server，必须能够从 Internet 访问 GitHub Enterprise Server。确保 Azure DNS 可以解析 GitHub Enterprise Server 名称，并且防火墙允许从 Azure 数据中心 IP 地址进行访问。要确定 IP 地址范围，请参阅 Microsoft Azure 数据中心 IP 范围。存在连接问题时遇到的常见错误消息是：

远程名称无法解析：“github-enterprise-server.contoso.com”

如果遇到此错误，请检查服务器是否可访问。有关详细信息，请参阅 Azure DNS 常见问题解答。

选择“项目设置”>“GitHub 连接”> GitHub Enterprise Server 进行首次连接。

或者，从“新建 GitHub 连接”对话框中，选择 GitHub Enterprise Server。
选择身份验证方法。

使用 OAuth 连接

选择在 Azure DevOps Services 中注册 OAuth 配置的步骤 4 中设置的配置，然后选择连接。

使用个人访问令牌连接

输入 GitHub Enterprise Server 的 URL 以及该服务器识别的“个人访问令牌”凭据。然后选择连接。

使用用户名和密码连接

输入 GitHub Enterprise Server 的 URL 以及该服务器识别的管理员帐户凭证，然后选择“连接”。
该对话框列出了你拥有 GitHub 管理权限的所有存储库。可以在我的和全部之间切换以确定是否显示其他存储库，然后勾选要添加的存储库。完成时选择保存。

提示

只能与一个 GitHub 组织下定义的存储库建立连接。若要将项目连接到其他 GitHub 组织中定义的其他存储库，必须添加另一个连接。
如果是首次从 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 Servers 2019 及更高版本仅支持与 GitHub Enterprise Server 存储库集成。不支持与其他 Git 存储库集成。

授予 Azure Boards 组织访问权限

如果 Azure Boards 与 GitHub 之间的集成未正常运行，则请验证是否已授予组织访问权限。

在 GitHub Web 门户中，从个人资料菜单打开设置。
在集成>授权的 OAuth 应用>Azure Boards 下选择应用程序。
在组织访问权限下，解决可能出现的所有问题。选择“授予”，向任何显示为具有“挂起的访问请求”的组织授予访问权限。

解决访问问题

当与 GitHub 的 Azure Boards 连接不再具有访问权限时，它会在用户界面中显示带有红色 X 的警报状态。将鼠标悬停在警报上，该警报指示凭据不再有效。为了更正此问题，请删除连接，并重新创建一个新连接。

失败的连接的屏幕截图。

要解决此问题，请考虑以下各项：

如果连接使用的是 OAuth：
- Azure Boards 应用程序对其中一个存储库的访问被拒绝。
- GitHub 可能不可用/无法访问。这种不可用性可能是由于服务中断或本地基础结构/网络问题导致的。可以从以下链接检查服务状态：
  - GitHub
  - Azure DevOps
  删除并重新创建与 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 组织 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# 提及时可能会出现意外结果。出现此问题的原因是，工作项 ID 在所有 Azure DevOps 组织中不是唯一的，因此 AB#12 可以引用 Contoso 或 Fabrikam 组织中的工作项。在提交消息或拉取请求中提及某一工作项时，两个组织均可尝试创建指向具有匹配 ID（如果存在）的工作项的链接。

通常，用户希望 AB# 提及链接到其中一个项目中的单个工作项。但是，如果这两个帐户中存在具有相同 ID 的工作项，则会为这两个工作项创建链接，这可能会导致混淆。

目前，无法解决此问题，因此建议只将一个 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 提交和 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>

FAQ（常见问题解答）

问：Azure DevOps 中的某些用户具有 GitHub 标识。是否需要将它们作为新的 GitHub 用户添加到我的组织中？

答：否。要求用户注销，然后在新的浏览器会话中使用其 GitHub 凭据重新登录到组织。此操作有助于将这些用户确定为具有有效的 GitHub 标识。

问：我是一名组织管理员，然后我打开了用于启用 GitHub 用户邀请的策略。为什么我无法邀请新的 GitHub 用户？

答：更改此设置后，请注销 Azure DevOps，然后在新的浏览器会话中使用 GitHub 凭据重新登录到组织 dev.azure.com/{organizationName} 或 organizationName.visualstudio.com。

问：我已用自己的 GitHub 凭据登录，但为什么无法邀请 GitHub 用户？

答：只有组织或项目管理员才能邀请新用户加入组织。你可能没有添加新用户所需的权限。请与管理员协作以便获取正确的权限，或是要求对方为你添加用户。

后续步骤

将 GitHub 提交和拉取请求关联到工作项

将 Azure Boards 连接到 GitHub（云）

先决条件

身份验证选项

将 Azure Boards 连接到 GitHub 存储库。