跳至主要内容

何时构建 GitHub App

构建集成时,您应考虑在以下情况下使用 GitHub App,而不是 OAuth 应用、个人访问令牌或 GitHub Actions。

使用 GitHub App 代替 OAuth 应用

一般情况下,GitHub 应用优于 OAuth 应用。

OAuth 应用和 GitHub 应用都使用 OAuth 2.0。

OAuth 应用只能代表用户操作,而 GitHub 应用可以代表用户操作,也可以独立于用户操作。

更多信息,请参阅“GitHub 应用和 OAuth 应用之间的区别”。

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

GitHub 应用提供增强的安全性

GitHub 应用提供对应用可以执行的操作的更多控制。GitHub 应用使用细粒度的权限,而不是 OAuth 应用使用的广泛范围。例如,如果您的应用需要读取存储库的内容,OAuth 应用将需要repo范围,这也会使应用编辑存储库内容和设置。GitHub 应用可以请求对存储库内容的只读访问权限,这将不允许应用执行编辑存储库内容或设置等更高级别的操作。

GitHub 应用还提供对存储库访问的更多控制。使用 GitHub 应用,安装该应用的用户或组织所有者可以决定该应用可以访问哪些存储库。相反,OAuth 应用可以访问授权该应用的用户可以访问的每个存储库。

GitHub 应用使用短期令牌。如果令牌泄露,令牌的有效期将更短,从而减少可能造成的损害。相反,OAuth 应用令牌在授权 OAuth 应用的人员撤销令牌之前不会过期。

这些安全功能通过限制如果您的应用凭据泄露可能造成的损害来增强 GitHub 应用的安全性。此外,这允许具有更严格安全策略的组织使用您的应用。

GitHub 应用可以独立运行或代表用户运行

GitHub 应用可以独立于用户运行。这对于不需要用户输入的自动化非常有益。

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

GitHub 应用不与用户帐户绑定,也不会占用 GitHub 上的席位。即使最初安装该应用的人员离开组织,GitHub 应用仍然保持已安装状态。这允许您的集成即使在人员离开您的团队后也能继续工作。

GitHub 应用具有可扩展的速率限制

使用安装访问令牌的 GitHub 应用的速率限制会随着存储库数量和组织用户数量而扩展。相反,OAuth 应用的速率限制较低,并且不会扩展。有关更多信息,请参阅“GitHub 应用的速率限制”。

GitHub 应用具有内置的 Webhook

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

API 访问略有不同

一般来说,GitHub 应用和 OAuth 应用可以发出相同的 API 请求。但是,也有一些区别。

  • 管理检查运行和检查套件的 REST API 仅适用于 GitHub 应用。
  • 企业级资源(例如企业对象本身)不适用于 GitHub 应用。这意味着 GitHub 应用无法调用诸如GET /enterprise/settings/license之类的端点。但是,企业拥有的组织和存储库资源可用。
  • 根据授予 GitHub 应用的权限和存储库访问权限,某些请求可能会返回不完整的数据。例如,如果您的应用发出请求以获取用户可以访问的所有存储库,则响应将仅包含也授予应用访问权限的存储库。

有关 GitHub 应用可用的 REST API 端点的更多信息,请参阅“GitHub 应用安装访问令牌可用的端点”。

在 GitHub 应用或个人访问令牌之间进行选择

如果您想代表用户或在组织中访问 GitHub 资源,或者您预期长期集成的应用,我们建议构建 GitHub 应用。

您可以使用个人访问令牌进行 API 测试或短期脚本。由于个人访问令牌与用户相关联,因此如果用户不再具有您需要的资源的访问权限,您的自动化可能会中断。安装在组织中的 GitHub 应用不依赖于用户。此外,与用户不同,GitHub 应用不会占用 GitHub 席位。

GitHub 支持两种类型的个人访问令牌,但建议您尽可能使用细粒度个人访问令牌代替个人访问令牌(经典版)。有关个人访问令牌的更多信息,请参阅“管理您的个人访问令牌”。

在 GitHub 应用或 GitHub Actions 之间进行选择

GitHub 应用和 GitHub Actions 都提供构建自动化和工作流工具的方法。

GitHub Actions 提供可在存储库中执行持续集成、部署任务和项目管理等作业的自动化。它们直接在 GitHub 托管的运行器机器或管理员设置的自托管运行器上运行。GitHub Actions 不会持续运行。GitHub Actions 工作流会响应其存储库中发生的事件运行,并且只能访问其设置的存储库的资源。但是,自定义操作可以在存储库和组织之间共享,允许开发人员重用和修改现有操作以满足他们的需求。GitHub Actions 还具有内置的密钥管理功能,您可以使用它来安全地与第三方服务交互并安全地管理部署密钥。

GitHub 应用会在您提供的服务器或计算基础设施上持续运行,或者在用户设备上运行。它们可以响应 GitHub Webhook 事件以及 GitHub 生态系统外部的事件。对于跨多个存储库或组织的操作,或者为其他组织提供托管服务,它们是一个不错的选择。当构建主要在 GitHub 外部发生或需要比 GitHub Actions 工作流分配的更多执行时间或权限的功能的工具时,GitHub 应用是最佳选择。

有关将 GitHub Actions 与 GitHub 应用进行比较的更多信息,请参阅“关于自定义操作”。

如果内置的GITHUB_TOKEN权限不足,您可以使用 GitHub 应用在 GitHub Actions 工作流中进行身份验证。有关更多信息,请参阅“在 GitHub Actions 工作流中使用 GitHub 应用进行身份验证的 API 请求”。