将 OAuth 应用迁移到 GitHub 应用

了解将 OAuth app 迁移到 GitHub App 的好处，以及如何迁移 OAuth app。

本文内容

从 OAuth apps 迁移到 GitHub Apps 的好处

建议通过 GitHub Apps 与 GitHub 集成。 与 OAuth apps 相比，GitHub Apps 提供了许多优势，包括：

  • 安全功能增强，例如细化权限、存储库访问权限选择以及生存期较短的令牌
  • 能够独立操作或代表用户执行操作
  • 可缩放速率限制
  • 内置 Webhook

有关详细信息，请参阅“关于创建 GitHub 应用”。

将 OAuth app 转换为 GitHub App

以下步骤概述了如何从 OAuth app 迁移到 GitHub App。 具体步骤取决于你的应用。

1. 查看 OAuth app

重新熟悉 OAuth app 的代码。 OAuth app 发出的 API 请求将用于确定为 GitHub App 选择哪些权限。

此外，还有一些 REST API 终结点不适用于 OAuth apps。 查看“适用于 GitHub Apps 安装访问令牌的终结点”，验证你使用的任何 REST 终结点是否适用于 GitHub Apps。

2. 注册 GitHub App

注册新的 GitHub App。 有关详细信息，请参阅“注册 GitHub 应用”。

与 OAuth app 相比，GitHub App 设置可以更好地控制。 一些关键的新增内容包括：

  • 与始终代表用户执行操作的 OAuth app 不同，你可以使 GitHub App 以自身或用户的身份执行操作。 如果不希望新的 GitHub App 代表用户执行操作，则可以跳过“标识和授权用户”设置。 有关详细信息，请参阅“关于使用 GitHub 应用进行身份验证”。

  • 当发生特定事件时，可以使用 Webhook 通知 GitHub App。 与必须通过 API 为每个存储库或组织配置的 OAuth apps Webhook 不同，Webhook 内置于 GitHub Apps 中。 注册 GitHub App 时，可以选择想要接收的 Webhook 事件。 此外，如果 OAuth app 当前使用轮询来确定是否发生了事件，请考虑改为订阅 Webhook 以帮助 GitHub App 保持在速率限制内。 有关详细信息，请参阅“将 Webhook 与 GitHub 应用配合使用”。

  • 如果使用 OAuth app，则当用户授权应用时请求范围。 如果使用 GitHub App，可以在应用设置中指定权限。 这些权限比范围更细化，这样你就能够仅选择应用所需的权限。 此外，这些权限映射到 REST API 终结点和 Webhook 事件，因此可以轻松确定 GitHub App 需要哪些权限才能访问特定的 REST API 终结点或订阅特定的 Webhook。 当前未记录 GraphQL 请求的权限。 有关详细信息，请参阅“为 GitHub Apps 选择权限”。

3. 修改应用的代码

注册 GitHub App，请调整旧 OAuth app 中的代码，以使用新的 GitHub App。

更新身份验证

你需要更新应用的代码来处理 GitHub App 的 API 身份验证。 GitHub App 可以通过三种方式进行身份验证：

如果使用 GitHub 的官方 Octokit.js 库，那么可使用内置的 App 对象进行身份验证。 有关示例，请参阅“使用 REST API 和 JavaScript 编写脚本”和“构建响应 Webhook 事件的 GitHub 应用”。

查看速率限制

查看 OAuth apps 和 GitHub Apps 之间的速率限制差异。 GitHub Apps 使用滑动速率限制规则，可以根据组织中的存储库和用户数增加速率上限。 有关详细信息，请参阅“GitHub 应用的速率限制”。

如果可能，请勿使用轮询，而是考虑改用条件请求和订阅 Webhook，以帮助保持在速率限制内。 有关条件请求的详细信息，请参阅“使用 REST API 的最佳做法”。 若要详细了解如何将 Webhook 与 GitHub App 配合使用，请参阅“将 Webhook 与 GitHub 应用配合使用”和“构建响应 Webhook 事件的 GitHub 应用”。

测试代码

测试新的 GitHub App 以确保代码按预期工作。

4. 公开新的 GitHub App

如果希望其他帐户能够使用新的 GitHub App，请确保应用公开。有关详细信息，请参阅“将 GitHub 应用程序设为公共或私有”。

5. 指示用户迁移

新 GitHub App 准备就绪后，指示旧 OAuth app 的用户迁移到新的 GitHub App。 无法自动迁移用户。 每个用户必须自行安装和/或授权你的 GitHub App。

作为应用所有者，你应该号召鼓励用户安装/授权新的 GitHub App 并撤销对旧 OAuth app 的授权。 还应更新任何文档或用户界面元素。

提示用户安装你的 GitHub App

如果希望 GitHub App 以应用自身身份发出 API 请求或访问组织或存储库资源，则用户必须安装你的 GitHub App。 当用户在其帐户或组织上安装 GitHub App 时，将选择应用可以访问的存储库，并授予应用请求的组织和存储库权限。

为了帮助用户安装 GitHub App，可以添加指向应用网页的链接，用户可以单击该链接来安装 GitHub App。 安装 URL 的格式为 http(s)://HOSTNAME/github-apps/YOUR_APP_NAME/installations/new。 将 YOUR_APP_NAME 替换为 GitHub App 的短化名称，可在 GitHub App 的设置页上的“公共链接”字段中找到该名称。

若要预先选择 OAuth app 有权访问的任何存储库，可以将 /permissions 和查询参数追加到安装 URL。 这有助于用户授予 GitHub App 访问 OAuth app 已经可以访问的存储库的权限。 查询参数是：

  • suggested_target_id：安装 GitHub App 的用户或组织的 ID。 此参数是必需的。
  • repository_ids[]：要选择用于安装的存储库 ID。 如果省略，则选择所有存储库。 可以预先选择的仓库最大数量为 100。 要获取 OAuth app 有权访问的存储库列表，请使用列出已验证用户的存储库和列出组织存储库终结点。

例如：http(s)://HOSTNAME/github-apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID。

有关安装 GitHub Apps 的详细信息，请参阅“从第三方途径安装 GitHub Apps”和“安装自己的 GitHub 应用”。

提示用户授权应用

如果希望 GitHub App 以用户身份发出 API 请求，用户必须授权该应用。 当用户授权应用时，他们授予应用代表他们执行操作的权限，且授予帐户应用请求的权限。 如果应用安装在组织帐户上，则该组织内每个用户都必须先授权该应用，应用才能代表他们执行操作。

若要提示用户授权你的应用，你将引导他们完成 Web 应用程序流或设备流。 有关详细信息，请参阅“为 GitHub 应用生成用户访问令牌”。

若要详细了解授权 GitHub Apps，请参阅“授权 GitHub Apps”。

鼓励用户撤销 OAuth app 访问权限

还应鼓励用户撤销对旧 OAuth app 的访问权限。 这将帮助你实现从 OAuth app 的完全转换，并有助于保护用户数据的安全。 有关详细信息，请参阅“审查授权的 OAuth 应用”。

更新任何接口或文档

应更新与应用相关的任何用户界面或文档，以反映从 OAuth app 到 GitHub App 的更改。

6. 删除旧 OAuth app 的 Webhook

当用户安装 GitHub App 并授予对存储库的访问权限时，你应该删除旧 OAuth app 的任何 Webhook。 如果新的 GitHub App 和旧的 OAuth app 响应同一事件的 Webhook，则用户可能会观察到重复的行为。

若要删除存储库 Webhook，可以使用 added 操作侦听 installation_repositories Webhook。 当 GitHub App 收到该事件时，你可以使用 REST API 删除 OAuth app 的这些存储库上的 Webhook。 有关详细信息，请参阅 Webhook 事件和有效负载 和 存储库 Webhook 的 REST API 终结点。

同样，若要删除组织 Webhook，可以使用 created 操作侦听 installation Webhook。 当 GitHub App 收到组织的该事件时，你可以使用 REST API 删除该组织上的 Webhook 以及 OAuth app 的相应存储库。 有关详细信息，请参阅“Webhook 事件和有效负载”、“适用于组织 Webhook 的 REST API 终结点”和“存储库 Webhook 的 REST API 终结点”。

7. 删除旧 OAuth app

用户迁移到新的 GitHub App 后，你需要删除旧 OAuth app。 这样有助于避免滥用 OAuth app 的凭据。 此操作还将撤销 OAuth app 的所有剩余授权。 有关详细信息，请参阅“删除 OAuth 应用”。 如果已在 GitHub Marketplace 中上架 OAuth app，则可能需要联系 GitHub 支持 从市场中删除该应用。