将 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 Boards 或 Azure DevOps 项目。 如果没有项目，请创建一个。
  • 你必须是“项目管理员”组的成员。 如果你创建了项目，则拥有权限。
  • 你必须是要连接到的 GitHub 存储库的管理员或所有者。 只要你是多个存储库的管理员，就可以连接到多个 GitHub 存储库。

身份验证选项

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

GitHub.com

GitHub Enterprise Server

注意

如果选择使用 PAT 连接 Github，请确保在 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 Server 的 Web 门户。

    Screenshot of sign in for GitHub Enterprise server.

  2. 打开“设置”>“开发人员设置”>“Oauth 应用”>“新建 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 应用程序的“客户端 ID”和“客户端密码”。

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

在 Azure DevOps Services 中注册 OAuth 配置

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

  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，必须能够从 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 进行首次连接。

    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 Server 的 URL 以及该服务器识别的“个人访问令牌”凭据。 然后选择“连接”。

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

    使用用户名和密码连接

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

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

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

    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 Servers 2019 及更高版本仅支持与 GitHub Enterprise Server 存储库集成。不支持与其他 Git 存储库集成。

授予 Azure Boards 组织访问权限

如果 Azure Boards 与 GitHub 之间的集成没有按预期实现，请验证是否已授予组织访问权限。

  1. 在 GitHub Web 门户中，从个人资料菜单打开“设置”。
    Screenshot of open profile, choose Settings.

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

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

    Screenshot of Organization access with organizations without access.

解决访问问题

当与 GitHub 的 Azure Boards 连接不再具有访问权限时，它会在用户界面中显示带有红色 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 连接中断的问题

如果已从 Azure DevOps Server 迁移到已有 GitHub Enterprise 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# 提及链接到工作项时可能会获得意外的结果。 出现此问题的原因是，工作项 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>

后续步骤

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