跳至主要内容

选择 GitHub 应用的权限

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

关于 GitHub 应用权限

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

虽然默认情况下 GitHub 应用没有任何权限,但它们在代表用户操作时确实具有读取公共资源的隐式权限。当用户授权该应用代表他们操作时,GitHub 应用可以使用生成的 user access token 向 REST API 和 GraphQL API 发出请求以读取公共资源。要详细了解如何代表用户操作,请参阅“代表用户使用 GitHub 应用进行身份验证”。

应用权限分为存储库、组织或帐户权限。存储库权限允许你的应用访问属于已安装应用的帐户所拥有的存储库相关资源。组织权限允许你的应用访问已安装应用的组织相关资源(如果已安装在组织帐户上)。帐户权限允许你的应用访问用户相关资源,如果用户也授权了你的应用。有关用户授权应用的更多信息,请参阅“代表用户使用 GitHub 应用进行身份验证”。

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

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

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

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

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

选择 Webhook 访问权限

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

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

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

选择 REST API 访问权限

每个端点的 REST API 参考文档都会说明该端点是否适用于 GitHub 应用,并说明应用使用该端点所需的权限。某些端点可能需要多个权限,而某些端点可能需要多个权限中的一个。有关 GitHub 应用可以使用哪些 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 目录中的操作文件,请请求“工作流”存储库权限。

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

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