将 OAuth 应用迁移到 GitHub 应用

从 OAuth 应用迁移到 GitHub 应用的优势

GitHub 应用是与 GitHub 集成的推荐方法。与 OAuth 应用相比，GitHub 应用具有许多优势，包括

增强的安全功能，例如细粒度的权限、对仓库访问的控制以及短期令牌
能够独立行动或代表用户行动的能力
可扩展的速率限制
内置的 Webhook

更多信息，请参见“关于创建 GitHub Apps”。

将 OAuth 应用转换为 GitHub 应用

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

1. 检查您的 OAuth 应用

重新熟悉您的 OAuth 应用的代码。您的 OAuth 应用发出的 API 请求将帮助您决定为您的 GitHub 应用选择哪些权限。

此外，OAuth 应用无法使用一些 REST API 端点。请查看“GitHub 应用安装访问令牌可用的端点”，验证您使用的任何 REST 端点是否可用于 GitHub 应用。

2. 注册 GitHub 应用

注册一个新的 GitHub 应用。更多信息，请参见“注册 GitHub 应用”。

与 OAuth 应用相比，您可以更好地控制 GitHub 应用设置。一些关键新增功能包括：

与始终代表用户操作的 OAuth 应用不同，您可以让您的 GitHub 应用以自身身份或代表用户采取操作。如果您不希望您的新 GitHub 应用代表用户采取操作，您可以跳过“识别和授权用户”设置。更多信息，请参见“关于使用 GitHub 应用进行身份验证”。
您可以使用 Webhook 在发生特定事件时通知您的 GitHub 应用。与必须通过 API 为每个仓库或组织配置的 OAuth 应用的 Webhook 不同，Webhook 内置于 GitHub 应用中。注册 GitHub 应用时，您可以选择要接收的 Webhook 事件。此外，如果您的 OAuth 应用目前使用轮询来确定是否发生了事件，请考虑改为订阅 Webhook，以帮助您的 GitHub 应用保持在速率限制内。更多信息，请参见“使用 GitHub 应用的 Webhook”。
使用 OAuth 应用时，用户授权您的应用时，您会请求作用域。使用 GitHub 应用时，您会在应用设置中指定权限。这些权限比作用域更细粒度，使您只需选择应用所需的权限。此外，这些权限映射到 REST API 端点和 Webhook 事件，因此您可以轻松确定您的 GitHub 应用需要哪些权限才能访问特定的 REST API 端点或订阅特定的 Webhook。目前没有为 GraphQL 请求记录权限。更多信息，请参见“为 GitHub 应用选择权限”。

3. 修改应用代码

更新身份验证

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

作为应用本身，以便获取或修改 GitHub 应用注册的详细信息或创建安装访问令牌。更多信息，请参见“以 GitHub 应用身份进行身份验证”。
作为应用安装，以便代表自身采取行动。更多信息，请参见“以 GitHub 应用安装身份进行身份验证”。
代表用户，以便将操作归因于用户。更多信息，请参见“代表用户使用 GitHub 应用进行身份验证”。

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

查看速率限制

查看 OAuth 应用和 GitHub 应用之间的速率限制差异。GitHub 应用对速率限制使用滑动规则，该规则可以根据组织中的仓库数量和用户数量而增加。更多信息，请参见“GitHub 应用的速率限制”。

如果可能，请考虑使用条件请求并订阅 Webhook，而不是轮询，以帮助您保持在速率限制内。有关条件请求的更多信息，请参见“使用 REST API 的最佳实践”。有关使用 Webhook 与您的 GitHub 应用的更多信息，请参见“使用 GitHub 应用的 Webhook”和“构建响应 Webhook 事件的 GitHub 应用”。

4. 公布您的新 GitHub 应用

如果您希望其他帐户能够使用您的新 GitHub 应用，请确保您的应用是公开的。如果您想让您的 GitHub 应用更容易被发现，请在 GitHub Marketplace 中列出您的应用。更多信息，请参见“关于 GitHub 应用的 Marketplace”和“将 GitHub 应用设为公开或私有”。

5. 指导您的用户迁移

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

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

提示用户安装您的 GitHub 应用

如果希望您的 GitHub 应用代表自身发出 API 请求或访问组织或仓库资源，则用户必须安装您的 GitHub 应用。当用户在其帐户或组织上安装 GitHub 应用时，他们会选择应用可以访问哪些仓库，并向应用授予其请求的组织和仓库权限。

为了帮助您的用户安装您的 GitHub 应用，您可以向您的应用网页添加一个链接，用户可以点击该链接来安装 GitHub 应用。安装 URL 的格式为 https://github.com/apps/YOUR_APP_NAME/installations/new。将 YOUR_APP_NAME 替换为 GitHub 应用的简写名称，您可以在 GitHub 应用设置页面上的“公共链接”字段中找到它。

要预选 OAuth 应用已访问的任何仓库，您可以将 /permissions 和查询参数附加到安装 URL。这有助于用户向您的 GitHub 应用授予 OAuth 应用已有的仓库访问权限。查询参数为：

suggested_target_id：安装您的 GitHub 应用的用户或组织的 ID。此参数是必需的。
repository_ids[]：要为安装选择的仓库 ID。如果省略，则选择所有仓库。最多可以选择 100 个仓库进行预选。要获取 OAuth 应用已访问的仓库列表，请使用列出已认证用户的仓库和列出组织仓库端点。

例如：https://github.com/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 应用的更多信息，请参见“从 GitHub Marketplace 为您的个人帐户安装 GitHub 应用”、“从 GitHub Marketplace 为您的组织安装 GitHub 应用”、“从第三方安装 GitHub 应用”和“安装您自己的 GitHub 应用”。

提示用户授权您的应用

如果希望您的 GitHub 应用代表用户发出 API 请求，则用户必须授权该应用。当用户授权应用时，他们会授予应用代表他们操作的权限，并授予应用请求的帐户权限。如果应用安装在组织帐户上，则该组织中的每个用户都必须授权该应用，以便该应用代表他们操作。

要提示用户授权您的应用，您将引导他们完成 Web 应用程序流程或设备流程。更多信息，请参见“为 GitHub 应用生成用户访问令牌”。

有关授权 GitHub 应用的更多信息，请参见“授权 GitHub 应用”。

鼓励您的用户撤销 OAuth 应用访问权限

您还应鼓励您的用户撤销对旧 OAuth 应用的访问权限。这将帮助您完全从 OAuth 应用过渡，并有助于保护用户的數據安全。更多信息，请参见“查看您已授权的 OAuth 应用”。

更新任何界面或文档

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

6. 删除旧 OAuth 应用的 Webhook

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

要删除存储库 Webhook，您可以侦听带有 `added` 操作的 `installation_repositories` Webhook。当您的 GitHub 应用收到该事件时，您可以使用 REST API 删除 OAuth 应用在这些存储库上的 Webhook。更多信息，请参见“Webhook 事件和有效负载”和“存储库 Webhook 的 REST API 端点”。

类似地，要删除组织 Webhook，您可以侦听带有 `created` 操作的 `installation` Webhook。当您的 GitHub 应用为某个组织收到该事件时，您可以使用 REST API 删除该组织及其 OAuth 应用相应存储库上的 Webhook。更多信息，请参见“Webhook 事件和有效负载”、“组织 Webhook 的 REST API 端点”和“存储库 Webhook 的 REST API 端点”。

7. 删除旧 OAuth 应用

一旦您的用户迁移到您的新 GitHub 应用，您就应该删除您的旧 OAuth 应用。这将有助于避免滥用 OAuth 应用的凭据。此操作还将撤销所有 OAuth 应用剩余的授权。更多信息，请参见“删除 OAuth 应用”。如果您的 OAuth 应用列在 GitHub Marketplace 上，您可能需要联系 GitHub 支持以先从 Marketplace 中删除您的应用。

本文内容