Skip to main content

决定何时生成 GitHub 应用

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

使用 GitHub App 而不是 OAuth app

一般来说,GitHub Apps 优先于 OAuth apps。

OAuth apps 和 GitHub Apps 使用 OAuth 2.0。

OAuth apps 只能代表用户执行操作,而 GitHub Apps 可以代表用户或独立于用户执行操作。

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

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

GitHub Apps 增强安全性

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

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

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

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

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

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

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

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

GitHub Apps 的速率限制可缩放

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

GitHub Apps 具有内置的 Webhook

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

API 访问略有不同

通常,GitHub Apps 和 OAuth apps 可以发出相同的 API 请求。 但是,两者存在一些差异:

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

有关可用于 GitHub Apps 的 REST API 终结点的详细信息,请参阅“适用于 GitHub Apps 安装访问令牌的终结点”。

在 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 (classic)。 有关 personal access tokens 的详细信息,请参阅“管理个人访问令牌”。

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

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

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

GitHub Apps 持续运行在你提供的服务器或计算基础结构上,或者运行在用户设备上。 可以响应 GitHub Webhook 事件以及来自 GitHub 生态系统之外的事件。 该应用适用于跨多个存储库或组织的操作或者为其他组织提供托管服务。 当所生成的工具的功能主要在 GitHub 之外发挥作用或需要比分配给 GitHub Actions 工作流的更多的执行时间或权限时,GitHub App 是最佳选择。

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

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