跳至主要内容

选择 GitHub App 的权限

GitHub App 的权限决定了该应用可以使用 GitHub 的哪些 API 以及可以接收哪些 Webhook。

关于 GitHub App 权限

GitHub 应用默认没有任何权限。注册 GitHub 应用时,您可以为该应用选择权限。您选择的权限将决定该应用可以使用 GitHub 的哪些 API 以及可以订阅哪些 Webhook。您应为应用选择所需的最低权限。

尽管 GitHub Apps 默认没有任何权限,但它们在代表用户执行操作时确实具有读取公共资源的隐式权限。当用户授权应用代表其执行操作时,GitHub App 可以使用生成的 user access token 向 REST API 和 GraphQL API 发出请求以读取公共资源。要了解有关代表用户执行操作的更多信息,请参阅“代表用户使用 GitHub App 进行身份验证”。

应用权限分为仓库权限、组织权限和账户权限。仓库权限允许您的应用访问与安装应用的账户拥有的仓库相关的资源。如果应用安装在组织账户上,则组织权限允许您的应用访问与安装应用的组织相关的资源。如果用户也授权了您的应用,则账户权限允许您的应用访问与用户相关的资源。有关应用的用户授权的更多信息,请参阅“代表用户使用 GitHub App 进行身份验证”。

当用户在其账户或组织上安装应用时,他们会看到并授予应用请求的仓库和组织权限。他们还会看到应用可以为各个用户请求的账户权限列表。当用户授权应用代表其执行操作时,他们会看到并授予应用请求的账户权限。

使用 user access token 的 API 请求是否成功取决于用户的权限以及应用的权限。例如,如果应用被授予写入仓库内容的权限,但用户只能读取内容,则 user access token 只能读取内容。使用 installation access token 的 API 请求是否成功仅取决于应用的权限。

您可以随时修改应用的权限。当您修改权限时,安装了应用的每个账户的所有者都会被提示批准新权限。如果账户所有者不批准新权限,则其安装将继续使用旧权限。

某些 Webhook 和 API 访问需要“管理”权限。如果您的应用需要“管理”权限,请考虑在应用的主页上说明此要求。这将帮助用户了解您的应用为何需要高级别权限。

有关在 GitHub App 注册期间指定权限的更多信息,请参阅“注册 GitHub App”。有关修改权限的更多信息,请参阅“修改 GitHub App 注册”。

选择 Webhook 访问权限

Webhook 文档指示每个 Webhook 是否可用于 GitHub Apps。对于您要订阅的每个 Webhook,请参阅 Webhook 文档以查看 GitHub App 需要订阅该 Webhook 的哪些权限。有关更多信息,请参阅“Webhook 事件和有效负载”。

例如,如果希望您的应用订阅 team 事件,则您的应用必须具有“成员”组织权限。

在您的 GitHub App 注册页面上,可用的 Webhook 事件会随着您更改应用权限而更改。如果您未为您的 GitHub App 选择足够的权限来订阅事件,则该事件不会作为选项显示在您的应用注册页面上。

选择 REST API 访问权限

每个端点的 REST API 参考文档都说明了该端点是否适用于 GitHub Apps,并说明了应用使用该端点所需的权限。某些端点可能需要多个权限,而某些端点可能需要多个权限中的一个。有关 GitHub App 使用每个权限可以访问哪些 REST API 端点的概述,请参阅“GitHub Apps 所需的权限”。

例如,要使用 GET /orgs/{org}/dependabot/secrets 端点,您的应用必须至少具有“组织 Dependabot 机密”权限的读取级别权限。

如果您的应用使用权限不足的 REST API 请求,则 API 将返回 403 响应。

为了帮助您选择正确的权限,您将在 REST API 响应中收到 X-Accepted-GitHub-Permissions 标头。该标头将告诉您访问端点所需的权限。有关更多信息,请参阅“REST API 故障排除”。

选择 GraphQL API 访问权限

对于 GraphQL 请求,您应该测试您的应用以确保它具有您要执行的 GraphQL 查询和变异所需的权限。

如果您的应用使用权限不足的 GraphQL API 查询或变异,则 API 将返回 401 响应。

选择 Git 访问权限

如果希望您的应用使用 installation 或 user access token 对基于 HTTP 的 Git 访问进行身份验证,则应请求“内容”仓库权限。如果您的应用特别需要访问或编辑 .github/workflows 目录中的 Actions 文件,请请求“工作流”仓库权限。

然后,您可以将 access token 用作 HTTP 密码。将 TOKEN 替换为 access token

git clone https://x-access-token:[email protected]/owner/repo.git