通过

将 Azure Boards 连接到 GitHub（云）

  • 项目

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 DevOps 项目。 如果没有项目，请创建一个项目。

  • 权限：

    • 是项目管理员组的成员。 如果你创建了项目，则拥有权限。
    • 必须是要连接到的 GitHub 存储库的管理员或所有者。 只要你是多个存储库的管理员，就可以连接到多个 GitHub 存储库。

身份验证选项

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

GitHub.com

GitHub Enterprise Server

注意

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

将 Azure Boards 连接到 GitHub 存储库。

  1. 登录到你的项目 (https://dev.azure.com/{Your_Organization/Your_Project})。

  2. 选择“项目设置”>“GitHub 连接”。

    打开“项目设置”>“GitHub 连接”的屏幕截图。

  3. 如果是首次从项目进行连接，请选择连接 GitHub 帐户以使用 GitHub 帐户凭证。

    首次使用 GitHub 凭据进行连接的屏幕截图。

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

    使用 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，则将看到以下消息：

    没有更多存储库需要连接的消息的屏幕截图。

  3. 输入 GitHub 凭证。 如果你已启用双因素身份验证，请输入 GitHub 发送给你的验证码，然后选择验证。 否则，系统将自动识别你的 GitHub 组织，因为你的 GitHub 帐户已与你的 Azure DevOps Services 帐户相关联。

添加 GitHub 存储库

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

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

    显示 GitHub 存储库的屏幕截图。

    提示

    为了避免意外的 AB# 提及链接，建议将 GitHub 存储库连接到单个 Azure DevOps 组织中的项目。 如果将同一 GitHub 存储库连接到多个 Azure DevOps 组织中的项目，则可能会导致问题。 有关详细信息，请参阅 GitHub 与 Azure Boards 集成疑难解答。

    如果所有存储库都已连接到当前组织或其他组织，则显示以下消息：

    没有更多存储库需要连接的消息的屏幕截图。

  2. 进行选择后，请选择保存。

确认连接

  1. 查看显示的 GitHub 页面，然后选择批准、安装和授权。

    显示“确认 GitHub 存储库”的屏幕截图。

  2. 提供 GitHub 密码进行确认。

  3. 完成后，应会看到列出与所选存储库建立的新连接。

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

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

使用 PAT 添加 GitHub 连接

建议使用 GitHub 帐户凭据连接到 GitHub 存储库。 如果需要使用 PAT，请执行以下步骤。

提示

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

  1. 选择“个人访问令牌”。

    “新建 GitHub 连接”对话框、选择“个人访问令牌”的屏幕截图。

    要创建 GitHub PAT，请转到 GitHub 开发人员设置 > 个人访问令牌。

  2. 输入 PAT 并选择连接。

    显示已输入 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 Server 的 Web 门户。

    GitHub Enterprise 服务器登录的屏幕截图。

  2. 打开“设置”>“开发人员设置”>“Oauth 应用”>“新建 OAuth 应用”。

    显示“新建 OAuth 应用”序列的屏幕截图。

  3. 输入注册信息。

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

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

    例如：

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

    显示要注册的应用的屏幕截图。

  4. 选择注册应用程序。

  5. 将显示已注册的 OAuth 应用程序的“客户端 ID”和“客户端密码”。

    已注册 OAuth 应用程序的客户端 ID 和客户端密钥的屏幕截图。

在 Azure DevOps Services 中注册 OAuth 配置

  1. 登录到 Azure DevOps Services 的 Web 门户。

  2. 将 GitHub Enterprise OAuth 配置添加到组织。

  3. 在“组织设置”中，选择“Oauth 配置”>“添加 Oauth 配置”。

    打开“组织设置”、OAuth 配置的屏幕截图。

  4. 输入你的信息，然后选择“创建”。

    “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 常见问题解答。

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

    首次连接，选择“GitHub Enterprise Server”。

    或者，从“新建 GitHub 连接”对话框中，选择 GitHub Enterprise Server。

    “新建 GitHub 连接”对话框、选择“GitHub Enterprise Server”的屏幕截图。

  2. 选择身份验证方法。

    显示身份验证方法对话框的屏幕截图。

    使用 OAuth 连接

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

    “新建 GitHub Enterprise 连接”、“OAuth 连接”对话框的屏幕截图。

    使用个人访问令牌连接

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

    “新建 GitHub Enterprise 连接”、“个人访问令牌连接”对话框的屏幕截图。

    使用用户名和密码连接

    输入 GitHub Enterprise Server 的 URL 以及该服务器识别的管理员帐户凭证，然后选择“连接”。

    “新建 GitHub Enterprise 连接”屏幕、”用户名连接“对话框的屏幕截图。

  3. 该对话框列出了你拥有 GitHub 管理权限的所有存储库。 可以在我的和全部之间切换以确定是否显示其他存储库，然后勾选要添加的存储库。 完成时选择“保存”。

    所列存储库的屏幕截图。

    提示

    只能与一个 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 Web 门户中，从个人资料菜单打开设置。
    打开的个人资料的屏幕截图，选择“设置”。

  2. 在集成>授权的 OAuth 应用>Azure Boards 下选择应用程序。

  3. 在组织访问权限下，解决可能出现的所有问题。 选择“授予”，向任何显示为具有“挂起的访问请求”的组织授予访问权限。

    “组织访问权限”的屏幕截图，其中显示了一些没有访问权限的组织。

解决访问问题

当与 GitHub 的 Azure Boards 连接失去访问权限时，用户界面中会出现带有红色 X 的警报状态。 将鼠标悬停在警报上，会发现凭据不再有效。 要解决此问题，请删除连接并创建新的连接。

失败的连接的屏幕截图。

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

  • 如果连接使用的是 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 组织 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 的工作项，从而造成混淆。

要避免此问题，请将单个 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>

常见问题

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

答: 不是。 要求用户注销，然后从新的浏览器会话中使用其 GitHub 凭据重新登录到组织。 此操作将确认他们的 GitHub 身份。

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

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

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

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

后续步骤

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