Skip to main content

关于应用程序

你可以构建与 GitHub API 的集成来增加灵活性并减少自己工作流程中的摩擦。 你也可以与 GitHub Marketplace 上的其他 API 集成。

GitHub 上的应用程序允许您自动化并改进工作流程。 可以生成应用来改进工作流。也可以在 GitHub Marketplace 中分享或销售应用。 若要了解如何在 GitHub Marketplace 中上架应用,请参阅“GitHub 市场入门”。

GitHub 应用程序是官方推荐的与 GitHub 集成的方式,因为它们提供更精细的数据访问权限,但 GitHub 支持 OAuth Apps 和 GitHub Apps。 有关选择应用类型的信息,请参阅“GitHub 应用与 OAuth 应用的区别”。

如果将应用与 GitHub Actions 一起使用,并想要修改工作流文件,则必须使用包含 workflow 作用域的 OAuth 令牌代表用户进行身份验证。 用户必须具有包含工作流程文件的仓库的管理员或写入权限。 有关详细信息,请参阅“了解 OAuth 应用的作用域”。

有关生成 GitHub App 的过程演练,请参阅“生成第一个 GitHub App”。

关于 GitHub Apps

GitHub Apps 是 GitHub 中的一流产品。 GitHub App 应用程序以自己的名义运行,通过 API 直接使用自己的身份进行操作,这意味着您无需作为独立用户维护自动程序或服务帐户。

GitHub Apps 可以直接安装在组织和个人帐户上,并获得对特定仓库的访问权限。 它们拥有内置 web 挂钩和狭窄的特定权限。 设置 GitHub App时,可以选择希望它访问的仓库。 例如,可以设置一个名为在存储库中MyGitHub写入问题且octocat写入 存储库的应用octocat。 要安装 GitHub App,您必须是组织所有者或在仓库中具有管理员权限。

默认情况下,只有组织所有者才可管理组织中 GitHub 的设置。 要允许其他用户管理组织中的 GitHub 应用程序,所有者可以向他们授予 GitHub 应用程序管理员权限。 请参阅“GitHub 应用管理器”,了解如何在组织中添加和删除 GitHub 应用管理器。

GitHub Apps 是需要托管在某处的应用程序。 有关涵盖服务器和托管的分步说明,请参阅“生成第一个 GitHub App”。

要改进自己的工作流程,可以创建一个包含多个脚本或整个应用程序的 GitHub App,然后将此应用程序连接至许多其他工具。 例如,您可以将 GitHub Apps 连接至 GitHub、Slack、自己可能拥有的其他内部应用程序、电子邮件程序或其他 API。

创建 GitHub Apps 时,请记住以下方法:

  • 用户或组织最多可以拥有 100 个 GitHub 应用。

  • GitHub App 的操作应独立于用户(除非此应用使用用户到服务器令牌)。 为使用户到服务器的访问令牌更安全,您可以使用将在 8 小时后过期的访问令牌,以及可交换新访问令牌的刷新令牌。 有关详细信息,请参阅“刷新用户到服务器访问令牌”。

  • 请确保 GitHub App 与特定仓库集成。

  • GitHub App 应该连接到个人帐户或组织。

  • 不要指望 GitHub App 知道并尽其所能。

  • 如果您只需要“使用GitHub登录”服务,请不要使用 GitHub App。 但是 GitHub App 可以使用用户标识流让用户登录和执行其他操作。

  • 如果只想充当 GitHub 用户并执行用户所能执行的所有操作,请不要生成 GitHub App。

  • 如果将应用与 GitHub Actions 一起使用,并想要修改工作流文件,则必须使用包含 workflow 作用域的 OAuth 令牌代表用户进行身份验证。 用户必须具有包含工作流程文件的仓库的管理员或写入权限。 有关详细信息,请参阅“了解 OAuth 应用的作用域”。

若要开始开发 GitHub Apps,请从“创建 GitHub App”开始。若要了解如何使用 GitHub App 清单创建预配置的 GitHub Apps,请参阅“从清单创建 GitHub Apps”。

关于 OAuth Apps

OAuth2 是一种协议,它允许外部应用程序请求授权在不使用密码的情况下访问用户 GitHub 帐户中的私有信息。 此协议优先于基本验证,因为令牌可能仅限于特定类型的数据,用户可以随时撤销。

警告:从 OAuth App 撤销所有权限将会删除应用程序代表用户生成的所有 SSH 密钥,包括 部署密钥

OAuth App 使用 GitHub 作为身份提供程序以验证为授予应用程序访问权限的用户。 这意味着,当用户授予 OAuth App 访问权限时,将授权访问其帐户有权访问的所有存储库,以及他们所属的、未阻止第三方访问的任何组织。

如果要创建比简单脚本的处理范围更复杂的流程,构建 OAuth App 是一个很好的选择。 请注意,OAuth Apps 是需要托管在某处的应用程序。

创建 OAuth Apps 时,请记住以下几点:

  • 一个用户或组织最多可以拥有 100 个 OAuth 应用。
  • OAuth App 在所有 GitHub 中(例如,在提供用户通知时)应始终代表经身份验证的 GitHub 用户。
  • 通过为经身份验证的用户启用“使用 GitHub 进行登录”,OAuth App 可用作身份提供程序。
  • 如果您希望应用程序作用于单个仓库,请不要构建 OAuth App。 使用 repo OAuth 作用域,OAuth Apps 可以作用于经身份验证用户的所有存储库。
  • 不要构建 OAuth App 作为团队或公司的应用程序。 OAuth Apps 将验证为单个用户,因此,如果有人创建了 OAuth App 供公司使用,那么一旦他们离开公司,其他人将无法访问它。
  • 如果将 OAuth 应用程序与 GitHub Actions 一起使用并且想要修改工作流文件,则 OAuth 标记必须具有 workflow 作用域,并且用户必须对包含工作流文件的存储库具有所有者或写入权限。 有关详细信息,请参阅“了解 OAuth 应用的作用域

有关 OAuth Apps 的详细信息,请参阅“创建 OAuth App”和“注册应用”。

个人访问令牌

个人访问令牌是一个字符串,其功能类似于 OAuth 令牌,可以通过作用域指定其权限。 个人访问令牌还与密码类似,但您能拥有很多令牌,而且可以随时撤销对每个令牌的访问权限。

例如,您可以启用个人访问令牌,以写入仓库。 如果随后运行 cURL 命令或编写在存储库中创建问题的脚本,则需要传递个人访问令牌以进行身份验证。 您可以将个人访问令牌存储为环境变量,以免每次使用时都要输入。

使用个人访问令牌时,请牢记以下几点:

  • 记得只能用此令牌代表您自己。
  • 您可以执行一次性 cURL 请求。
  • 您可以运行个人脚本。
  • 不要为整个团队或公司设置脚本。
  • 不要设置共享个人帐户来充当机器人用户。
  • 请为您的个人访问令牌设置期限,以帮助保护您的信息安全。

确定要构建的集成

在开始创建集成之前,您需要确定使用 GitHub API 访问、验证和交互的最佳方式。 下图提供了一些问题,您在决定是否对集成使用个人访问令牌、GitHub Apps 或 OAuth Apps 时可以考虑这些问题。

应用程序问题流程简介

请考虑关于您的集成需要如何操作及它需要访问什么等问题:

  • 我的集成是只像我一样,还是更像一个应用程序?
  • 我是否希望它作为单独的实体独立于我运行?
  • 它是否能访问我可以访问的一切,或者说我想限制它的访问权限?
  • 它是简单还是复杂? 例如,个人访问令牌对简单的脚本和 cURL 有益,而 OAuth App 可以处理更复杂的脚本。

请求支持

有关 GitHub Apps、OAuth Apps 和 API 开发的问题、漏洞报告和讨论,请访问 APIs and Integrations discussions on GitHub Community。 该讨论由 GitHub 工作人员管理和维护,但不能保证发布到论坛的问题都会得到 GitHub 工作人员的回复。

请考虑使用联系人表单直接联系 GitHub 支持

  • 要保证得到 GitHub 工作人员的回应
  • 涉及敏感数据或私人问题的支持请求
  • 功能请求
  • 关于 GitHub 产品的反馈