注意:请考虑生成 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://<em>HOSTNAME</em>/api/v3/users/codertocat -I
HTTP/2 200
X-OAuth-Scopes: repo, user
X-Accepted-OAuth-Scopes: user
X-OAuth-Scopes
列出令牌已授权的范围。X-Accepted-OAuth-Scopes
列出操作检查的范围。
可用的范围
名称 | 说明
-----|-----------| site_admin
| 向站点管理员授予对 GitHub Enterprise Server 管理 API 终结点的访问权限。 repo
| 授予对公共、内部和专用存储库的完全访问权限,包括对代码、提交状态、存储库邀请、协作者、部署状态和存储库 Webhook 的读写权限。 注意:除了存储库相关资源外,repo
范围还授予对组织拥有的资源(包括项目、邀请、团队成员身份和 Webhook)的管理权限。 此范围还授予对用户所拥有的项目的管理权限。
repo:status
| 授予对专用和内部存储库中的提交状态的读/写访问权限。 仅在授予其他用户或服务对专用存储库提交状态的访问权限而不授予对代码的访问权限时,才需要此范围。
repo_deployment
| 授予对 内部和专用存储库的部署状态的访问权限。 仅在授予其他用户或服务对部署状态的访问权限而不授予对代码的访问权限时,才需要此范围。 repo:invite
| 授予接受/拒绝存储库协作邀请的权限。 仅在授予其他用户或服务对邀请的访问权限而不授予对代码的访问权限时,才需要此范围。 admin:repo_hook
| 授予对专用或内部存储库中存储库挂钩的读取、写入、ping 和删除访问权限。 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:email
和 user:follow
。
read:user
| 授予读取用户个人资料数据的权限。
user:email
| 授予对用户电子邮件地址的读取权限。
user:follow
| 授予关注或取消关注其他用户的权限。delete_repo
| 授予删除可管理存储库的访问权限。 write:discussion
| 授予对团队讨论的读取和写入访问权限。
read:discussion
| 授予对团队讨论的读取权限。 write:packages
| 授予在 GitHub Packages 中上传或发布包的权限。 有关详细信息,请参阅“发布包”。
read:packages
| 授予从 GitHub Packages 下载或安装包的权限。 有关详细信息,请参阅“安装包”。
delete:packages
| 授予从 GitHub Packages 删除包的权限。 有关详细信息,请参阅“删除和恢复包”。
admin:gpg_key
| 全面管理 GPG 密钥。
write:gpg_key
| 创建、列出和查看 GPG 密钥的详细信息。
read:gpg_key
| 列出和查看 GPG 密钥的详细信息。 workflow
| 授予添加和更新 GitHub Actions 工作流文件的权限。 如果在同一仓库中的另一个分支上存在相同的文件(具有相同的路径和内容),则工作流程文件可以在没有此作用域的情况下提交。 工作流文件可以公开可能有不同范围集的 GITHUB_TOKEN
。 有关详细信息,请参阅“自动令牌身份验证”。
admin:enterprise
| 完全掌控企业功能。 有关详细信息,请参阅 GraphQL API 文档中的“管理企业帐户”。
包括 manage_runners:enterprise
和 read:enterprise
。
manage_runners:enterprise
| 完全掌控企业内部的自承载运行程序。 有关详细信息,请参阅“关于自托管运行程序”。 read:enterprise
| 读取企业资料中的所有数据。 不包括企业成员或组织的配置文件数据。
注意:OAuth app 可以在初始重定向中请求范围。 可使用 %20
以空格分隔多个范围来指定它们:
https://github.com/login/oauth/authorize?
client_id=...&
scope=user%20repo_deployment
请求的作用域和授予的作用域
scope
属性列出了附加到用户授予的令牌的范围。 通常,这些作用域与您请求的作用域相同。
但是,用户可以编辑其范围,实际授予应用程序更少的权限(相比你最初请求的权限)。 此外,用户还可以在 OAuth 流程完成后编辑令牌范围。
你应该意识到这种可能性,并相应地调整应用程序的行为。
如果用户选择授予更少的权限(相比你最初请求的权限),妥善处理这种错误情况非常重要。 例如,应用程序可以警告或以其他方式告诉用户,他们可用的功能会减少或者无法执行某些操作。
此外,应用程序总是可以将用户送回流程以获取更多权限,但不要忘记,用户总是可以说不。
请查看身份验证基础知识指南,其中提供了有关处理可修改令牌范围的提示。
标准化作用域
请求多个范围时,将用标准化的范围列表保存令牌,而放弃其他请求的范围隐式包含的那些范围。 例如,请求 user,gist,user:email
将生成仅具有 user
和 gist
范围的令牌,因为使用 user:email
范围授予的权限包含在 user
范围中。