警告:将访问令牌视为密码。 有关详细信息,请参阅“确保 personal access token 安全”。
关于 personal access token
使用 GitHub API 或命令行时,可使用 Personal access token 替代密码向 GitHub Enterprise Cloud 进行身份验证。
Personal access token 旨在代表你自己访问 GitHub 资源。 若要代表组织访问资源,或为长时间的集成而访问,应使用 GitHub App。 有关详细信息,请参阅“关于创建 GitHub 应用”。
令牌具有与令牌所有者相同的访问资源和对这些资源执行操作的能力,并且还受到授予令牌的任何范围或权限的限制。 令牌无法向用户授予额外访问权限功能。 例如,可以为 personal access token 配置 admin:org
作用域,但如果令牌的所有者不是组织所有者,则令牌不会授予对组织的管理访问权限。
personal access token 的类型
GitHub 目前支持两种类型的 personal access token:fine-grained personal access token 和 personal access tokens (classic)。 GitHub 建议尽可能使用 fine-grained personal access token 而不是 personal access tokens (classic)。
所有 fine-grained personal access token 和 personal access tokens (classic) 都与生成它们的用户相关联,如果用户失去对资源的访问权限,则会变为非活动状态。
组织所有者可以设置策略来限制 personal access tokens (classic) 对其组织的访问,并且企业所有者可以限制 personal access tokens (classic) 对企业或企业所有的组织的访问。 有关详细信息,请参阅“为组织设置个人访问令牌策略”。
Fine-grained personal access token
与 personal access tokens (classic) 相比,Fine-grained personal access token 具有几个安全优势:
- 每个令牌只能访问单个用户或组织拥有的资源。
- 每个令牌只能访问特定的存储库。
- 每个令牌都被授予特定的权限,这些权限比授予 personal access tokens (classic) 的范围提供更多的控制。
- 每个令牌都必须具有到期日期。
- 组织所有者可要求必须获取对可访问组织中资源的任何 fine-grained personal access token 的批准。
- 企业所有者可要求必须获取对 fine-grained personal access token 的批准,它可以访问该企业拥有的组织中的资源。
Personal access tokens (classic)
Personal access tokens (classic) 不太安全。 但是,某些功能目前仅适用于 personal access tokens (classic):
- 只有 personal access tokens (classic) 对不由你或你所属的组织拥有的公共存储库具有写入访问权限。
- 只有 personal access tokens (classic) 对企业拥有的内部存储库自动具有写入访问权限。 Fine-grained personal access token 必须授予对内部存储库的访问权限。
- 外部协作者只能使用 personal access tokens (classic) 访问他们参与协作处理的组织存储库。
- 只有 personal access tokens (classic) 才能访问企业。 (Fine-grained personal access token可以访问企业拥有的组织。)
- 少数 REST API 终结点仅支持 personal access tokens (classic)。 若要检查某个终结点是否还支持 fine-grained personal access token,请参阅该终结点的文档,或参阅“可用于细粒度的个人访问令牌的终结点”。
如果选择使用 personal access token (classic),请记住它将授予对有权访问的组织内的所有存储库以及个人帐户中的所有个人存储库的访问权限。
作为安全预防措施,GitHub 会自动删除一年内未使用过的 personal access token。 为了提供进一步的安全性,强烈建议将过期时间添加到 personal access token。
确保 personal access token 安全
Personal access token 类似于密码,它们具有相同的固有安全风险。 创建新的 personal access token 之前,请考虑是否有更安全的身份验证方法可供使用:
- 若要从命令行访问 GitHub,可以使用 GitHub CLI 或 Git 凭据管理器,而不是创建 personal access token。
- 在 GitHub Actions 工作流中使用 personal access token 时,请考虑是否可以改用内置
GITHUB_TOKEN
。 有关详细信息,请参阅“自动令牌身份验证”。
如果无法使用这些选项,但必须创建 personal access token,请考虑使用其他 CLI 服务安全地存储令牌。
在脚本中使用 personal access token 时,可以将令牌存储为机密,并通过 GitHub Actions 运行脚本。 有关详细信息,请参阅“在 GitHub Actions 中使用机密”。还可以将令牌存储为 Codespaces 机密,并在 Codespaces 中运行脚本。 有关详细信息,请参阅“管理 GitHub Codespaces 特定于帐户的机密”。
有关最佳做法的详细信息,请参阅“确保 API 凭据安全”。
创建 fine-grained personal access token
注意:Fine-grained personal access token 目前为 beta,可能会有变动。 若要留下反馈,请参阅反馈讨论。
1。 验证电子邮件地址(如果尚未验证)。 1. 在 GitHub 任意页的右上角,单击个人资料照片,然后单击“设置”。
-
在左侧边栏中,单击“ 开发人员设置”。
-
请在左侧边栏的“ Personal access token”下,单击“细粒度令牌” 。
-
单击“生成新令牌”。
-
在“令牌名称”下,输入令牌的名称。
-
在“过期时间”下,选择令牌的过期时间。
-
(可选)在“说明”下,添加说明来描述令牌的用途。
-
在“资源所有者”下,选择资源所有者。 令牌只能访问所选资源所有者拥有的资源。 除非你所属的组织选择加入 fine-grained personal access token,否则不会显示该组织。 有关详细信息,请参阅“为组织设置个人访问令牌策略”。 如果所选组织需要执行 SAML 单一登录 (SSO),而你还没有活动的 SAML 会话,你可能需要执行该单一登录。
-
(可选)如果资源所有者是需要批准 fine-grained personal access token 的组织,请在资源所有者下方的框中输入请求的理由。
-
在“存储库访问权限”下,选择希望令牌访问的存储库。 应选择满足需求的最小存储库访问权限。 令牌始终包括对 GitHub 上所有公有存储库的只读访问权限。
-
如果在上一步中选择了“仅选择存储库”,则在“所选存储库”下拉列表下,选择希望令牌访问的存储库 。
-
在“权限”下,选择要授予令牌的权限。 根据指定的资源所有者和存储库访问权限,有存储库、组织和帐户权限这几种可能性。 应根据需要选择最小权限。
每个终结点的 REST API 参考文档都说明终结点是否适用于 fine-grained personal access token,并说明令牌使用终结点所需的权限。 某些终结点可能需要多个权限,而某些终结点可能需要多个权限之一。 有关 fine-grained personal access token 可通过各种权限访问哪些 REST API 终结点的概述,请参阅“细粒度个人访问令牌所需的权限”。
-
单击“生成令牌”。****
如果选择了某个组织作为资源所有者,并且该组织需要批准 fine-grained personal access token,则令牌将被标记为 pending
,直到组织管理员审核为止。 令牌在得到批准之前只能读取公共资源。 如果你是组织的所有者,请求将自动获得批准。 有关详细信息,请参阅“查看和撤销组织中的个人访问令牌”。
创建 personal access token (classic)
注意:组织所有者可以限制 personal access token (classic) 对其组织的访问。 如果尝试使用 personal access token (classic) 访问已禁用 personal access token (classic) 访问权限的组织中的资源,则请求将失败并出现 403 响应。 相反,必须使用 GitHub App、OAuth app 或 fine-grained personal access token。
注意:personal access token (classic) 可以访问你有权访问的每个存储库。 GitHub 建议改用 fine-grained personal access token,你可以将其限制为特定的存储库。 Fine-grained personal access token 还允许指定细粒度的权限,而不是宽泛的范围。
1。 验证电子邮件地址(如果尚未验证)。 1. 在 GitHub 任意页的右上角,单击个人资料照片,然后单击“设置”。
-
在左侧边栏中,单击“ 开发人员设置”。 1。 在左侧边栏的“ Personal access token”下,单击“令牌(经典)”。 1 。 选择“生成新令牌”,然后单击“生成新令牌(经典)”。
-
在“备注”字段中,为令牌提供一个描述性名称。
-
要为令牌提供到期时间,请选择“到期时间”,然后选择默认选项或单击“自定义”以输入日期 。
-
选择要授予此令牌的作用域。 若要使用令牌从命令行访问存储库,请选择“存储库”。 没有指定范围的令牌只能访问公共信息。 有关详细信息,请参阅“OAuth 应用的范围”。
-
单击“生成令牌”。****
-
(可选)要将新令牌复制到剪贴板,请单击 。
-
要使用令牌访问使用 SAML 单一登录的组织所拥有的资源,请对令牌进行授权。 有关详细信息,请参阅 GitHub Enterprise Cloud 文档中的“授权用于 SAML 单点登录的个人访问令牌."
删除 personal access token
如果不再需要 personal access token,请删除。 如果删除用于创建部署密钥的 personal access token,则也会删除部署密钥。
- 在 GitHub 任意页的右上角,单击个人资料照片,然后单击“设置”。
- 在左侧边栏中,单击“ 开发人员设置”。
- 在左侧边栏的“ Personal access token”下,单击“细化的令牌”或“令牌(经典)”,具体取决于要删除哪种类型的 personal access token。
- 在要删除的 personal access token 的右侧,单击“删除”。
在命令行上使用 personal access token
如果你有 personal access token,则可以在通过 HTTPS 执行 Git 操作时输入它,而不是密码。
例如,若要在命令行上克隆存储库,请输入以下 git clone
命令。 然后,系统会提示你输入用户名和密码。 当系统提示输入密码时,请输入 personal access token 而不是密码。
$ git clone https://github.com/USERNAME/REPO.git
Username: YOUR-USERNAME
Password: YOUR-PERSONAL-ACCESS-TOKEN
Personal access token 只能用于 HTTPS Git 操作。 如果存储库使用 SSH 远程 URL,则需要将远程 URL 从 SSH 切换到 HTTPS。
如果没有提示你输入用户名和密码,说明你的凭据可能已缓存在计算机上。 可在密钥链中更新凭据,从而用令牌替换旧密码。
可以使用 Git 客户端缓存 personal access token 而不是为每个 HTTPS Git 操作手动输入 personal access token。 Git 会将你的凭据临时存储在内存中,直到过期为止。 你还可以将令牌存储在 Git 可以在每个请求之前读取的纯文本文件中。 有关详细信息,请参阅“在 Git 中缓存 GitHub 凭据”。
延伸阅读
- “关于向 GitHub 验证”
- "令牌过期和吊销"