Skip to main content

为 GitHub Apps 选择权限

GitHub Apps 的权限决定了应用可以使用 GitHub 的 API 执行哪些操作,以及应用可以接收哪些 Webhook。

关于 GitHub App 权限

默认情况下,GitHub Apps 没有任何权限。 注册 GitHub App 时,可以选择该应用的权限。 你选择的权限决定了应用可以使用 GitHub 的 API 执行哪些操作,以及应用可以订阅的 Webhook。 你应选择应用所需的最小权限。

虽然 GitHub Apps 默认情况下没有任何权限,但在代表用户执行操作时,则具有读取公共资源的隐式权限。 当用户授权应用代表其执行操作时,GitHub App 可以使用生成的用户访问令牌向 REST API 和 GraphQL API 发出请求,以读取公共资源。 若要详细了解如何代表用户执行操作,请参阅“代表用户使用 GitHub 应用进行身份验证”。

应用权限分为存储库、组织或帐户权限。 存储库权限允许应用访问与安装应用的帐户拥有的存储库相关的资源。 如果应用安装在组织帐户上,则组织权限允许应用访问与安装应用的组织相关的资源。 如果某用户还授权了你的应用,则帐户权限允许应用访问与该用户相关的资源。 有关应用的用户授权的详细信息,请参阅“代表用户使用 GitHub 应用进行身份验证”。

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

使用用户访问令牌的 API 请求是否成功取决于用户的权限以及应用的权限。 例如,如果向应用授予了写入存储库内容的权限,但用户只能读取内容,则用户访问令牌也只能读取内容。 使用安装访问令牌的 API 请求是否成功仅取决于应用权限。

你可以随时修改应用权限。 修改权限时,系统会提示安装应用的每个帐户的所有者批准新权限。 如果帐户所有者未批准新权限,则其安装将继续使用旧权限。

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

若要详细了解如何在 GitHub App 注册期间指定权限,请参阅“注册 GitHub 应用”。 有关修改权限的详细信息,请参阅“修改 GitHub 应用注册”。

为 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 应用程序所需的权限”。

例如,若要使用 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 访问选择权限

如果希望应用使用安装或用户访问令牌对基于 HTTP 的 Git 访问进行身份验证,则应请求“内容”存储库权限。 如果应用专门需要访问或编辑 .github/workflows 目录中的 Actions 文件,请请求“工作流”存储库权限。

然后可以使用访问令牌作为 HTTP 密码。 将 TOKEN 替换为访问令牌:

git clone https://x-access-token:TOKEN@github.com/owner/repo.git