注意:请考虑生成 GitHub App 而不是 OAuth App。 GitHub App 使用精细的权限而不是范围,这让你可以更好地控制应用可以执行的操作。 有关详细信息,请参阅“GitHub 应用和 OAuth 应用之间的差异”和“About creating GitHub Apps”。
在 GitHub 上设置 OAuth 应用程序时,请求的作用域会在授权表单上显示给用户。
注意:如果你在构建 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 中安全事件的读取和写入权限
仅在授予其他用户或服务对安全事件的访问权限而不授予对代码的访问权限时,才需要此范围。 admin:repo_hook
| 授予对公共或专用存储库中存储库挂钩的读取、写入、ping 和删除访问权限。 repo
和 public_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 应用创建的组织挂钩执行这些操作。 Personal access token 只能对用户创建的组织挂钩执行这些操作。
gist
| 授予对 Gist 的写入权限。
notifications
| 授予:
对用户的通知的读取访问权限
对线程的“标记为读取”访问权限
对存储库的监视和取消监视访问权限,以及
对线程订阅的读取、写入和删除访问权限。
user
| 仅授予对个人资料的读取/写入权限。 请注意,此范围包括 user:email
和 user: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
。 有关详细信息,请参阅“自动令牌身份验证”。
注意:OAuth 应用可以在初始重定向中请求范围。 可使用 %20
以空格分隔多个范围来指定它们:
https://github.com/login/oauth/authorize?
client_id=...&
scope=user%20repo_deployment
请求的作用域和授予的作用域
scope
属性列出了附加到用户授予的令牌的范围。 通常,这些作用域与您请求的作用域相同。
但是,用户可以编辑其范围,实际授予应用程序更少的权限(相比你最初请求的权限)。 此外,用户还可以在 OAuth 流程完成后编辑令牌范围。
你应该意识到这种可能性,并相应地调整应用程序的行为。
如果用户选择授予更少的权限(相比你最初请求的权限),妥善处理这种错误情况非常重要。 例如,应用程序可以警告或以其他方式告诉用户,他们可用的功能会减少或者无法执行某些操作。
此外,应用程序总是可以将用户送回流程以获取更多权限,但不要忘记,用户总是可以说不。
请查看身份验证基础知识指南,其中提供了有关处理可修改令牌范围的提示。
标准化作用域
请求多个范围时,将用标准化的范围列表保存令牌,而放弃其他请求的范围隐式包含的那些范围。 例如,请求 user,gist,user:email
将生成仅具有 user
和 gist
范围的令牌,因为使用 user:email
范围授予的权限包含在 user
范围中。