关于创建 GitHub 应用

关于 GitHub Apps

GitHub App 是一种集成类型，你可以构建它来与 GitHub 交互并扩展其功能。可以构建 GitHub App 来提供灵活性并减少流程中的冲突，而无需登录用户或创建服务帐户。

GitHub Apps 的常见用例包括：

自动执行任务或后台进程
支持“使用 GitHub 登录”，允许用户使用其 GitHub 帐户登录，以便在生态系统中提供其标识
用作开发人员工具，允许用户登录到 GitHub App 来使用 GitHub，然后应用可以代表用户进行操作
将工具或外部服务与 GitHub 集成

GitHub Apps 是 GitHub 中的独立参与者。 GitHub App 以应用自身身份进行操作，这意味着你无需作为独立用户维护机器人或服务帐户。该应用还可以使用授予它的权限以用户身份进行身份验证并代表用户进行操作。

如果希望应用响应 GitHub 上的事件，则应用应订阅 Webhook。例如，你可能希望应用在拉取请求打开时发表评论。有关详细信息，请参阅“将 Webhook 与 GitHub 应用配合使用”。

在开发期间，可以在本地运行应用进行开发。应用可供生产使用后，应将应用部署到专用服务器。例如，可以使用 Azure 应用服务。

GitHub Apps 的权限和可见性

GitHub Apps 可以直接安装在组织和个人帐户上，并获得对特定仓库的访问权限。它们拥有内置 web 挂钩和狭窄的特定权限。设置 GitHub App时，可以选择该应用的特定权限。这些权限确定应用可以通过 GitHub API 执行哪些操作、应用可以代表登录用户执行哪些操作，以及应用可以接收哪些 Webhook。然后，在用户或组织帐户上安装应用时，安装应用的人员将决定在该帐户下应用可以访问哪些存储库。有关详细信息，请参阅“为 GitHub Apps 选择权限”。

默认情况下，只有组织所有者才可管理组织中 GitHub 的设置。若要允许其他用户更改组织拥有的 GitHub 应用的开发人员设置，所有者可以向他们授予 GitHub 应用管理器权限。 GitHub 应用管理器无法管理第三方应用程序。有关在组织中添加和删除 GitHub 应用管理器的详细信息，请参阅“组织中的角色”。

可以设置应用可见性，以控制谁可以安装它。可以将其设为公共应用，以便其他 GitHub 用户或组织都可以安装该应用，或将其设为专用应用，以便你只能在拥有该应用的帐户上进行安装。有关详细信息，请参阅“将 GitHub 应用程序设为公共或私有”。

何时使用 GitHub Apps

构建集成时，应考虑在以下场景中使用 GitHub App 而不是 OAuth App、personal access token 或 GitHub Actions。

使用 GitHub App 而不是 OAuth App

一般来说，GitHub App 优先于 OAuth App。

有关详细信息，请参阅“GitHub 应用和 OAuth 应用之间的差异”。

有关如何将现有 OAuth App 迁移到 GitHub App 的信息，请参阅“将 OAuth 应用程序迁移到 GitHub 应用程序”。

GitHub App 增强安全性

GitHub App 可以更好地控制应用可以执行的操作。与 OAuth App 使用的广泛范围不同，GitHub App 使用细化的权限。例如，如果应用需要读取存储库的内容，则 OAuth App 需要 repo 范围，应用也因此可以编辑存储库内容和设置。 GitHub App 可以请求对存储库内容的只读访问权限，这样应用不会执行更多特权操作，例如编辑存储库内容或设置。

GitHub App 也可以更好地控制存储库访问权限。使用 GitHub App，安装应用的用户或组织所有者可以决定应用可以访问哪些存储库。相反，OAuth App 可以访问授权应用的用户可以访问的所有存储库。

GitHub App 使用生存期较短的令牌。如果令牌泄漏，令牌的有效期将缩短，这样可以降低可能造成的损害。相反，在授权 OAuth App 的人员吊销令牌之前，OAuth App 令牌不会过期。

这些安全功能通过限制在应用凭据泄露时可能造成的损害，帮助强化 GitHub App 的安全。此外，安全策略更严格的组织也由此可以使用你的应用。

GitHub App 可以独立于用户进行操作，也可以代表用户执行操作

GitHub App 可以独立于用户进行操作。这有利于不需要用户输入的自动化。

与 OAuth App 类似，GitHub App 仍可以代表用户执行操作。与指示操作由应用执行的 OAuth App 不同，GitHub App 指示操作由应用代表用户执行。

GitHub App 未绑定到用户帐户，不会占用 GitHub Enterprise Server 上的席位。即使最初安装应用的人离开组织，GitHub App 也会保持安装状态。因此，即使有人离开团队，集成也能继续正常工作。

GitHub App 的速率限制可缩放

使用安装访问令牌的 GitHub App 的速率限制随存储库数和组织用户数而缩放。相反，OAuth Apps 的速率限制较低，并且无法缩放。有关详细信息，请参阅“GitHub 应用的速率限制”。

GitHub App 具有内置的 Webhook

GitHub App 具有内置的集中式 Webhook。 GitHub App 可以接收应用可以访问的所有存储库和组织的 Webhook 事件。相反，OAuth App 必须为每个存储库和组织单独配置 Webhook。

API 访问略有不同

通常，GitHub App 和 OAuth App 可以发出相同的 API 请求。但是，两者存在一些差异：

用于管理检查运行和检查套件的 REST API 仅适用于 GitHub App 。
企业资源仅适用于 OAuth App。
某些请求可能会返回不完整的数据，具体取决于授予 GitHub App 的权限和存储库访问权限。例如，如果应用发出获取用户可以访问的所有存储库的请求，则响应将仅包括应用也有权访问的存储库。

有关可用于 GitHub App 的 REST API 终结点的详细信息，请参阅“可用于 GitHub 应用程序的端点”。

在 GitHub App 或 personal access token 之间进行选择

如果要代表用户或组织中的用户访问 GitHub 资源，或者预期需要长期集成，建议生成 GitHub App。

可以将 personal access tokens 用于 API 测试或生存期较短的脚本。由于 personal access token 与用户关联，因此如果用户不再有权访问你需要的资源，自动化过程可能就会中断。在组织中安装的 GitHub App 不依赖于用户。此外，与用户不同，GitHub App 不会占用 GitHub 席位。

GitHub 支持两种类型的 personal access tokens，但建议尽可能使用 fine-grained personal access token 而不是 personal access tokens。有关 personal access tokens 的详细信息，请参阅“创建个人访问令牌”。

在 GitHub App 或 GitHub Actions 之间进行选择

GitHub Apps 和 GitHub Actions 都提供了生成自动化和工作流工具的方法。

GitHub Actions 提供自动化，可在存储库中执行持续集成、部署任务和项目管理等作业。它们直接在管理员设置的 GitHub 托管运行器计算机或自承载运行器上运行。 GitHub Actions 不会持久运行。它们运行是为了响应其存储库中发生的事件，并且仅有权访问为其设置的存储库的资源。但是，可以在存储库和组织之间共享它们，开发人员从而能够重复使用和修改现有操作来满足其需求。 GitHub Actions 还附带内置机密管理，可用于安全地与第三方服务交互并安全地管理部署密钥。

GitHub Apps 在所提供的服务器或计算基础结构上持久运行，并响应 Webhook 事件以及 GitHub 生态系统外部的事件。该应用适用于跨多个存储库或组织的操作或者为其他组织提供托管服务。所构建的工具的功能主要在 GitHub 之外发挥作用或需要比分配给执行的操作更多的时间时，GitHub App 是最佳选择。

有关比较 GitHub Actions 与 GitHub Apps 的详细信息，请参阅“关于自定义操作”。

如果内置 GITHUB_TOKEN 没有足够的权限，可以在 GitHub Actions 工作流中使用 GitHub App 进行身份验证。有关详细信息，请参阅“使用 GitHub Actions 工作流中的 GitHub App 发出经过身份验证的 API 请求”。

了解要生成的 GitHub App 类型

设计 GitHub App 有多种方法可供你选择，具体取决你希望应用包含的功能。

代表用户执行操作的 GitHub Apps

如果希望应用代表用户执行操作，则应使用用户访问令牌进行身份验证。这种类型的请求有时称为“用户到服务器”，这意味着应用将受到已授予应用的权限以及用户权限的限制。使用此模式时，用户必须先授权应用，然后应用才能执行操作。有关详细信息，请参阅“代表用户使用 GitHub 应用进行身份验证”。

可以使用 GitHub App 创建的一些自动化示例包括，其中应用代表用户执行操作：

使用 GitHub 作为生态系统标识提供者的 GitHub App
在 GitHub.com 顶部添加可能对 GitHub 用户有用的服务的 GitHub App。可以通过 GitHub Marketplace 或公开应用与其他开发人员共享应用

以应用自身身份执行操作的 GitHub Apps

如果希望应用以应用自身身份而不是用户身份执行操作，则应使用安装访问令牌进行身份验证。这种类型的请求有时称为“服务器到服务器”，这意味着应用将受到已授予应用的权限的限制。有关详细信息，请参阅“验证为 GitHub 应用程序安装”。

可以使用 GitHub App 创建的一些自动化示例包括，其中应用以自身身份执行操作：

使用 Webhook 响应给定一组特定条件的事件的 GitHub App。例如，可以创建使用标签的 REST API 终结点的自动化，在给定一组特定条件的情况下，为存储库中创建的每个新问题添加标签
帮助存储库参与者的 GitHub App。例如，应用可以在参与者创建拉取请求或发表评论后发布有用的资源
生成生存期较短的令牌以提供给其他 CI/CD 工具或从存储库中提取信息的 GitHub App