将 OAuth 应用迁移到 GitHub 应用

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

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

增强的安全功能，例如细粒度权限、对存储库访问的选择以及短期令牌
能够独立于用户或代表用户执行操作
可扩展的速率限制
内置的 Webhook

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

将 OAuth 应用转换为 GitHub 应用

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

1. 查看您的 OAuth 应用

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

此外，还有一些 REST API 端点不适用于 OAuth 应用。通过查看“适用于 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 App 安装身份进行身份验证”。
代表用户，为了将操作归因于用户。有关更多信息，请参阅“代表用户使用 GitHub App 进行身份验证”。

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

查看速率限制

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

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

4. 宣传您的新 GitHub App

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

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 中删除您的应用。