将 OAuth 应用迁移到 GitHub 应用

从 OAuth apps 迁移到 GitHub Apps 的好处

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

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

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

将 a 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应用”。

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

与始终代表用户执行操作的 OAuth app 不同，你可以让你的 GitHub App 以自身身份或代表用户执行操作。如果不希望新 GitHub App 用户代表用户执行操作，可以跳过“标识和授权用户”设置。有关详细信息，请参阅“关于使用 GitHub 应用进行身份验证”。
你可以使用 Webhook 在发生特定事件时向你的 GitHub App 发送通知。与用于 OAuth apps 的 Webhook 不同，你必须通过 API 为每个仓库或组织分别配置前者，而 GitHub Apps 内置了 Webhook。注册 GitHub App时，可以选择要接收的 Webhook 事件。此外，如果您的 OAuth app 当前使用轮询来确定某个事件是否已发生，请考虑改为订阅 Webhook，以帮助您的 GitHub App 保持在速率限制范围内。有关详细信息，请参阅“将 Webhook 与 GitHub 应用配合使用”。
使用 OAuth app，在用户授权你的应用时请求作用域。使用 a GitHub App时，可以在应用设置中指定权限。这些权限比范围更细化，这样你就能够仅选择应用所需的权限。此外，这些权限将映射到 REST API 终结点和 Webhook 事件，以便轻松确定访问特定 REST API 终结点或订阅特定 Webhook 所需的权限 GitHub App 。当前未记录 GraphQL 请求的权限。有关详细信息，请参阅“为GitHub应用选择权限”。

3. 修改应用的代码

注册了 GitHub App 后，请将旧 OAuth app 的代码调整为适配新的 GitHub App。

更新身份验证

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

以应用本身的身份，为了获取或修改有关 GitHub App 注册信息的详细信息，或创建安装访问令牌。有关详细信息，请参阅“以GitHub应用身份进行身份验证”。
以应用安装的形式，目的是以应用自身身份执行操作。有关详细信息，请参阅“验证为 GitHub 应用程序安装”。
以用户身份，目的是将操作分配给用户。有关详细信息，请参阅“代表用户使用 GitHub 应用进行身份验证”。

如果使用 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应用。

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 的 slug 化名称，你可以在你的 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应用。

鼓励用户撤销 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，可以使用 installation_repositories 操作侦听 added Webhook。当您的 GitHub App 收到该事件时，您可以使用 REST API 删除这些仓库上为您的 OAuth app 配置的 Webhook。有关详细信息，请参阅 Webhook 事件和有效负载和存储库 Webhook 的 REST API 终结点。

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

7. 删除旧版 OAuth app

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

在本文中