{"meta":{"title":"将 OAuth 应用迁移到 GitHub 应用","intro":"了解将您的 OAuth app 迁移到 GitHub App 的优势，以及如何迁移您的 OAuth app。","product":"应用","breadcrumbs":[{"href":"/zh/apps","title":"应用"},{"href":"/zh/apps/creating-github-apps","title":"创建GitHub应用"},{"href":"/zh/apps/creating-github-apps/about-creating-github-apps","title":"关于创建GitHub应用"},{"href":"/zh/apps/creating-github-apps/about-creating-github-apps/migrating-oauth-apps-to-github-apps","title":"从 OAuth apps 迁移"}],"documentType":"article"},"body":"# 将 OAuth 应用迁移到 GitHub 应用\n\n了解将您的 OAuth app 迁移到 GitHub App 的优势，以及如何迁移您的 OAuth app。\n\n## 从 OAuth apps 迁移到 GitHub Apps 的好处\n\nGitHub Apps 是与 GitHub 集成的推荐方式。 与 GitHub Apps 相比，OAuth apps 具有许多优势，包括：\n\n* 安全功能增强，例如细化权限、存储库访问权限选择以及生存期较短的令牌\n* 能够独立操作或代表用户执行操作\n* 可缩放的速率限制\n* 内置 Webhook\n\n有关详细信息，请参阅“[关于创建GitHub应用](/zh/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps)”。\n\n## 将 a OAuth app 转换为 GitHub App\n\n以下步骤概述了如何从 OAuth app 迁移到 GitHub App。 具体步骤取决于你的应用。\n\n### 1. 查看 OAuth app\n\n重新熟悉你的 OAuth app 的代码。 你 OAuth app 发出的 API 请求将帮助你确定要为你 GitHub App选择哪些权限。\n\n此外，还有一些 REST API 端点不适用于 OAuth apps。 通过查阅GitHub Apps，验证你使用的任何 REST 端点是否可用于 [](/zh/rest/authentication/endpoints-available-for-github-app-installation-access-tokens)。\n\n### 2. 注册 GitHub App\n\n注册一个新的 GitHub App。 有关详细信息，请参阅“[注册GitHub应用](/zh/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)”。\n\n与 a OAuth app相比，你可以更好地控制 GitHub App 设置。 一些关键的新增内容包括：\n\n* 与始终代表用户执行操作的 OAuth app 不同，你可以让你的 GitHub App 以自身身份或代表用户执行操作。 如果不希望新 GitHub App 用户代表用户执行操作，可以跳过“标识和授权用户”设置。 有关详细信息，请参阅“[关于使用 GitHub 应用进行身份验证](/zh/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)”。\n\n* 你可以使用 Webhook 在发生特定事件时向你的 GitHub App 发送通知。 与 OAuth apps 的 webhook 不同，你必须通过 API 为每个存储库或组织配置，webhook 内置在 GitHub Apps 中。 当你注册你的 GitHub App 时，你可以选择要接收的 webhook 事件。 此外，如果你的 OAuth app 当前使用轮询来确定事件是否已发生，请考虑改为订阅 webhook，以帮助你的 GitHub App 保持在速率限制内。 有关详细信息，请参阅“[将 Webhook 与 GitHub 应用配合使用](/zh/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-github-apps)”。\n\n* 使用 OAuth app，在用户授权你的应用时请求作用域。 使用 a GitHub App时，可以在应用设置中指定权限。 这些权限比范围更细化，这样你就能够仅选择应用所需的权限。 此外，这些权限将映射到 REST API 终结点和 Webhook 事件，以便轻松确定访问特定 REST API 终结点或订阅特定 Webhook 所需的权限 GitHub App 。 当前未记录 GraphQL 请求的权限。 有关详细信息，请参阅“[为GitHub应用选择权限](/zh/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app)”。\n\n### 3. 修改应用的代码\n\n一旦你注册了 GitHub App，请调整旧 OAuth app 的代码以与新 GitHub App 一起工作。\n\n#### 更新身份验证\n\n您需要更新应用的代码，以处理您的 GitHub App 的 API 身份验证。 A GitHub App 可以通过三种方式进行身份验证：\n\n* 作为应用本身，为了获取或修改关于 GitHub App 注册的详细信息或创建安装访问令牌。 有关详细信息，请参阅“[以GitHub应用身份进行身份验证](/zh/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app)”。\n* 以应用安装的形式，目的是以应用自身身份执行操作。 有关详细信息，请参阅“[验证为 GitHub 应用程序安装](/zh/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation)”。\n* 以用户身份，目的是将操作分配给用户。 有关详细信息，请参阅“[代表用户使用 GitHub 应用进行身份验证](/zh/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user)”。\n\n如果使用 GitHub'官方 Octokit.js 库，则可以使用内置 `App` 对象进行身份验证。 有关示例，请参阅“[使用 REST API 和 JavaScript 编写脚本](/zh/rest/guides/scripting-with-the-rest-api-and-javascript)”和“[构建响应 Webhook 事件的GitHub应用](/zh/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events)”。\n\n#### 查看速率限制\n\n查看 OAuth apps 和 GitHub Apps 之间的速率限制差异。\nGitHub Apps 对速率限制使用滑动规则，可以根据组织中的存储库数和用户数增加。 有关详细信息，请参阅“[GitHub 应用的速率限制](/zh/apps/creating-github-apps/registering-a-github-app/rate-limits-for-github-apps)”。\n\n如果可能，请勿使用轮询，而是考虑改用条件请求和订阅 Webhook，以帮助保持在速率限制内。 有关条件请求的详细信息，请参阅“[使用 REST API 的最佳做法](/zh/rest/using-the-rest-api/best-practices-for-using-the-rest-api)”。 有关将 webhook 与你的 GitHub App 一起使用的详细信息，请参阅 [将 Webhook 与 GitHub 应用配合使用](/zh/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-github-apps) 和 [构建响应 Webhook 事件的GitHub应用](/zh/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events)。\n\n#### 测试代码\n\n测试新 GitHub App 代码以确保代码按预期工作。\n\n### 4. 宣传你的新 GitHub App\n\n如果你希望其他账户能够使用你新的 GitHub App，请确保你的应用是公开的。 如果要使你的 GitHub App 更易发现，请在 GitHub Marketplace中列出你的应用。\n有关详细信息，请参阅 [关于 GitHub 应用市场](/zh/apps/github-marketplace/github-marketplace-overview/about-github-marketplace-for-apps) 和 [将GitHub应用公开或专用](/zh/apps/creating-github-apps/registering-a-github-app/making-a-github-app-public-or-private)。\n\n### 5. 指示用户迁移\n\n当新的 GitHub App 准备就绪后，通知旧 OAuth app 的用户迁移到新的 GitHub App。 无法自动迁移用户。 每个用户必须自行安装和/或授权你的 GitHub App。\n\n作为应用所有者，您应加入行动号召，引导用户安装/授权新的 GitHub App，并撤销对旧 OAuth app 的授权。 还应更新任何文档或用户界面元素。\n\n#### 提示用户安装你的 GitHub App\n\n如果希望 GitHub App 以自身身份发出 API 请求，或访问组织或存储库资源，用户必须安装你的 GitHub App。 当用户在其账户或组织中安装 GitHub App 时，他们会选择该应用可以访问哪些仓库，并向该应用授予其所请求的组织和仓库权限。\n\n若要帮助用户安装您的 GitHub App，您可以在应用的网页上添加一个链接，用户可以点击该链接来安装 GitHub App。 安装 URL 的格式为 `https://github.com/apps/YOUR_APP_NAME/installations/new`。 将 `YOUR_APP_NAME` 替换为你的 GitHub App 的慢段化名称，你可以在你的 GitHub App 的设置页面上的“公开链接”字段中找到该名称。\n\n若要预选 OAuth app 有权访问的任意仓库，可以将 `/permissions` 和查询参数附加到安装 URL 后。 这有助于用户授予你的 GitHub App 对其 OAuth app 已有权访问的存储库的访问权限。 查询参数是：\n\n* `suggested_target_id`：正在安装你的 GitHub App用户或组织的 ID。 此参数是必需的。\n* `repository_ids[]`：要选择用于安装的存储库 ID。 如果省略，则选择所有存储库。 可以预先选择的仓库最大数量为 100。 若要获取 OAuth app 有权访问的仓库列表，请使用 [列出经过身份验证的用户的仓库](/zh/rest/repos/repos#list-repositories-for-the-authenticated-user) 和 [列出组织仓库](/zh/rest/repos/repos#list-organization-repositories) 端点。\n\n例如： `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`。\n\n有关安装GitHub Apps的详细信息，请参阅 [通过 GitHub 市场安装 GitHub App 以用于个人帐户](/zh/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-personal-account)、[通过 GitHub 市场安装 GitHub App 以用于组织](/zh/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-organizations)、[从第三方途径安装 GitHub Apps](/zh/apps/using-github-apps/installing-a-github-app-from-a-third-party) 和 [安装自己的GitHub应用](/zh/apps/using-github-apps/installing-your-own-github-app)。\n\n#### 提示用户授权应用\n\n如果你希望 GitHub App 代表用户发出 API 请求，则用户必须授权该应用。 当用户授权应用时，他们授予应用代表他们执行操作的权限，且授予帐户应用请求的权限。 如果应用安装在组织帐户上，则该组织内每个用户都必须先授权该应用，应用才能代表他们执行操作。\n\n若要提示用户授权你的应用，你将引导他们完成 Web 应用程序流或设备流。 有关详细信息，请参阅“[为 GitHub 应用生成用户访问令牌](/zh/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)”。\n\n有关授权 GitHub Apps的详细信息，请参阅 [授权GitHub应用](/zh/apps/using-github-apps/authorizing-github-apps)。\n\n#### 鼓励用户撤销 OAuth app 访问权限\n\n你还应鼓励你的用户撤销你的旧 OAuth app 的访问权限。 这将帮助你彻底弃用 OAuth app，并帮助确保你的用户数据安全。 有关详细信息，请参阅“[审查授权的 OAuth 应用](/zh/apps/oauth-apps/using-oauth-apps/reviewing-your-authorized-oauth-apps)”。\n\n#### 更新任何接口或文档\n\n你应更新任何与你的应用相关的用户界面或文档，以反映从 OAuth app 到 GitHub App 的更改。\n\n### 6. 移除你的旧 OAuth app 的 webhook\n\n当用户安装你的 GitHub App 并授予对存储库的访问权限时，你应该移除你的旧 OAuth app 的任何 webhook。 如果新的 GitHub App 和旧的 OAuth app 都对同一事件的 Webhook 作出响应，用户可能会看到重复的行为。\n\n若要删除存储库 Webhook，可以使用 `installation_repositories` 操作侦听 `added` Webhook。 当你的 GitHub App 接收到该事件时，你可以使用 REST API 为你的 OAuth app 删除那些存储库上的 webhook。 有关详细信息，请参阅 [Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads?actionType=added#installation_repositories) 和 [存储库 Webhook 的 REST API 终结点](/zh/rest/repos/webhooks#delete-a-repository-webhook)。\n\n同样，若要删除组织 Webhook，可以使用 `installation` 操作侦听 `created` Webhook。 当你的 GitHub App 接收到针对组织的该事件时，你可以使用 REST API 为你的 OAuth app 删除该组织和相应存储库上的 webhook。 有关详细信息，请参阅“[Webhook 事件和有效负载](/zh/webhooks/webhook-events-and-payloads?actionType=created#installation)”、“[用于组织 Webhooks 的 REST API 接口节点](/zh/rest/orgs/webhooks#delete-an-organization-webhook)”和“[存储库 Webhook 的 REST API 终结点](/zh/rest/repos/webhooks#delete-a-repository-webhook)”。\n\n### 7. 删除你的旧 OAuth app\n\n当您的用户已迁移到新的 GitHub App 后，您应删除旧的 OAuth app。 这将有助于避免滥用 OAuth app 的凭据。 此操作还将撤销所有 OAuth app剩余的授权。 有关详细信息，请参阅“[删除 OAuth 应用](/zh/apps/oauth-apps/maintaining-oauth-apps/deleting-an-oauth-app)”。 如果您的 OAuth app 已在 GitHub Marketplace 上列出，您可能需要先联系 GitHub 支持，将您的应用从该市场中移除。"}