Skip to main content

OAuth 应用的范围

通过作用域,您可以准确指定所需的访问权限类型。 作用域限制 OAuth 标记的访问权限。 它们不会授予超出用户权限范围的任何额外权限。

注意:请考虑生成 GitHub App 而不是 OAuth app。 GitHub Apps 使用精细的权限而不是范围,这让你可以更好地控制应用可以执行的操作。 有关详细信息,请参阅“GitHub 应用和 OAuth 应用之间的差异”和“关于创建 GitHub 应用”。

在 GitHub 上设置 OAuth app 应用时,请求的范围会在授权表单上显示给用户。

注意:如果你在构建 GitHub 应用,则不需要在授权请求中提供范围。 有关详细信息,请参阅“代表用户使用 GitHub 应用进行身份验证”。

如果 OAuth app 无法访问浏览器(如 CLI 工具),则无需为用户指定向应用程序验证的作用域。 有关详细信息,请参阅“授权 OAuth 应用”。

检查标头以查看您拥有哪些 OAuth 作用域,以及 API 操作接受什么:

$ curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.github.com/users/codertocat -I
HTTP/2 200
X-OAuth-Scopes: repo, user
X-Accepted-OAuth-Scopes: user
  • X-OAuth-Scopes 列出令牌已授权的范围。
  • X-Accepted-OAuth-Scopes 列出操作检查的范围。

可用的范围

名称描述
(no scope)授予对公共信息(包括用户个人资料信息、仓库信息和 gist)的只读权限
repo授予对公共、内部和专用仓库的完全访问权限,包括代码、提交状态、仓库邀请、协作者、部署状态和仓库 Webhook 的读写权限。 注意:除了存储库相关资源外,repo 范围还授予对组织拥有的资源(包括项目、邀请、团队成员身份和 Webhook)的管理权限。 此范围还授予对用户所拥有的项目的管理权限。
repo:status授予对公共、专用和内部仓库中的提交状态的读写权限。 仅在向其他用户或服务授予对专用存储库提交状态的访问权限而不授予对代码的访问权限时,才需要此范围。
repo_deployment授予对公共和专用仓库的部署状态的访问权限。 仅在向其他用户或服务授予对部署状态的访问权限而“不”__ 授予对代码的访问权限时,才需要此范围。
public_repo限制对公共存储库的访问权限。 这包括对公共仓库和组织的代码、提交状态、仓库项目、协作者以及部署状态的读取/写入权限。 带有星标的公共存储库也需要此权限。
repo:invite授予接受/拒绝仓库协作邀请的权限。 仅在向其他用户或服务授予对邀请的访问权限而“不”__ 授予对代码的访问权限时,才需要此范围。
security_events授予下列权限:
code scanning API 中安全事件的读取和写入权限
secret scanning API 中安全事件的读取和写入权限
仅在向其他用户或服务授予对安全事件的访问权限而“不”__ 授予对代码的访问权限时,才需要此范围。
admin:repo_hook授予对公共、专用或内部仓库中挂钩的读取、写入、ping 和删除访问权限。 repopublic_repo 范围授予对存储库(包括存储库挂钩)的完全访问权限。 使用 admin:repo_hook 范围将访问权限限制为仅存储库挂钩。
write:repo_hook授予对公共、专用或内部仓库中挂钩的读取、写入和 ping 访问权限。
read:repo_hook授予对公共、专用或内部仓库中挂钩的读取和 ping 访问权限。
admin:org全面管理组织及其团队、项目和成员。
write:org对组织成员身份、组织项目和团队成员身份的读写权限。
read:org对组织成员身份、组织项目和团队成员身份的只读权限。
admin:public_key全面管理公钥。
write:public_key创建、列出和查看公钥的详细信息。
read:public_key列出和查看公钥的详细信息。
admin:org_hook授予对组织挂钩的读取、写入、ping 和删除权限。 注意:OAuth 令牌只能对由 OAuth app 创建的组织挂钩执行这些操作。 Personal access token 只能对用户创建的组织挂钩执行这些操作。
gist授予对 Gist 的写权限。
notifications授予下列权限:
对用户的通知的读取访问权限
对会话的“标记为读取”访问权限
对存储库的监视和取消监视访问权限,以及
对会话订阅的读取、写入和删除访问权限。
user仅授予对个人资料的读写权限。 请注意,此范围包括 user:emailuser:follow
read:user授予对用户个人资料数据的读取权限。
user:email授予对用户电子邮件地址的读取权限。
user:follow授予对关注或取消关注其他用户的访问权限。
project访问对用户和组织 projects 的读写权限。
read:project授予对用户和组织 projects 的只读权限。
delete_repo授予对可管理仓库的删除权限。
write:packages授予在 GitHub Packages 中上传或发布包的权限。 有关详细信息,请参阅“发布包”。
read:packages授予从 GitHub Packages 下载或安装包的权限。 有关详细信息,请参阅“安装包”。
delete:packages授予从 GitHub Packages 删除包的权限。 有关详细信息,请参阅“删除和恢复包”。
admin:gpg_key全面管理 GPG 密钥。
write:gpg_key创建、列出和查看 GPG 密钥的详细信息。
read:gpg_key列出和查看 GPG 密钥的详细信息。
codespace授予创建和管理 Codespace 的权限。 Codespaces 可以暴露可能有不同范围集的 GITHUB_TOKEN。 有关详细信息,请参阅“GitHub Codespaces 中的安全性”。
workflow授予添加和更新 GitHub Actions 工作流文件的权限。 如果在同一仓库中的另一个分支上存在相同的文件(具有相同的路径和内容),则工作流程文件可以在没有此作用域的情况下提交。 工作流文件可以公开可能有不同范围集的 GITHUB_TOKEN。 有关详细信息,请参阅“自动令牌身份验证”。
admin:enterprise授予对企业功能的完全控制权限。 有关详细信息,请参阅 GraphQL API 文档中的“管理企业帐户”。

包括 manage_runners:enterprisemanage_billing:enterprise、 和 read:enterprise
manage_runners:enterprise授予对企业内部自托管运行器的完全控制权限。 有关详细信息,请参阅“关于自托管运行程序”。
manage_billing:enterprise读取和写入企业账单数据。 有关详细信息,请参阅“计费的 REST API 终结点”。
read:enterprise读取企业资料中的所有数据。 不包括企业成员或组织的资料数据。
read:audit_log读取审核日志数据。

注意:OAuth app 可以在初始重定向中请求范围。 可使用 %20 以空格分隔多个范围来指定它们:

https://github.com/login/oauth/authorize?
  client_id=...&
  scope=user%20repo_deployment

请求的作用域和授予的作用域

scope 属性列出了附加到用户授予的令牌的范围。 通常,这些作用域与您请求的作用域相同。 但是,用户可以编辑其范围,实际授予应用程序更少的权限(相比你最初请求的权限)。 此外,用户还可以在 OAuth 流程完成后编辑令牌范围。 你应该意识到这种可能性,并相应地调整应用程序的行为。

如果用户选择授予更少的权限(相比你最初请求的权限),妥善处理这种错误情况非常重要。 例如,应用程序可以警告或以其他方式告诉用户,他们可用的功能会减少或者无法执行某些操作。

此外,应用程序总是可以将用户送回流程以获取更多权限,但不要忘记,用户总是可以说不。

请查看身份验证基础知识指南,其中提供了有关处理可修改令牌范围的提示。

标准化作用域

请求多个范围时,将用标准化的范围列表保存令牌,而放弃其他请求的范围隐式包含的那些范围。 例如,请求 user,gist,user:email 将生成仅具有 usergist 范围的令牌,因为使用 user:email 范围授予的权限包含在 user 范围中。