管理个人访问令牌

在命令行或 API 中验证身份时，可以使用personal access token来代替GitHub密码。

在本文中

警告

将访问令牌视为密码一样保管。 有关详细信息，请参阅确保您的personal access token设备安全。

关于 personal access token

在使用 GitHub API 或命令行访问 GitHub 时，Personal access token 是替代密码进行身份验证的选项。

Personal access token 旨在代表您本人访问 GitHub 资源。 为了代表组织访问资源或实现长期集成，您应该使用一个 GitHub App。 有关详细信息，请参阅“关于创建GitHub应用”。

令牌具有与令牌所有者相同的访问资源和对这些资源执行操作的能力，并且还受到授予令牌的任何范围或权限的限制。 令牌无法向用户授予额外访问权限功能。例如，可以为personal access token配置admin:org范围，但如果令牌的持有者不是组织的所有者，那么令牌将不会授予组织的管理权限。

personal access token 的类型

GitHub 当前支持两种类型的 personal access tokens： fine-grained personal access tokens 和 personal access tokens (classic)。 GitHub 建议尽量使用 fine-grained personal access tokens，而不是 personal access tokens (classic)。

注意

Fine-grained personal access tokens 虽然更安全且更可控，但无法完成一个 personal access token (classic) 可以完成的每个任务。 有关详细信息，请参阅以下限制Fine-grained personal access tokens部分。

fine-grained personal access token 和 personal access tokens (classic) 都与生成它们的用户相关联，如果用户无法访问资源，这些项目将变为非活动状态。

组织所有者可以设置策略来限制 personal access tokens (classic) 对其组织的访问，企业所有者可以限制 personal access tokens (classic) 对企业或企业所拥有组织的访问。 有关详细信息，请参阅“为组织设置个人访问令牌策略”。

Fine-grained personal access token

Fine-grained personal access tokens 具有多个安全优势，但 personal access tokens (classic) 也存在一些限制，可能会阻止你在每种方案中使用它们。 可以在下面的部分中找到这些限制以及我们的修复计划。

如果在你的场景中可以使用 fine-grained personal access token，你将受益于以下改进：

  • 每个令牌仅限于访问单个用户或组织所拥有的资源。
  • 每个令牌可以进一步限制为仅访问该用户或组织的特定仓库。
  • 每个令牌都拥有特定且精细的权限，相比授予 personal access tokens (classic) 的范围，这提供了更强的控制力。
  • 组织所有者可以要求对任何能够访问该组织资源的 fine-grained personal access token 进行审批。
  • 企业所有者可以要求对任何能够访问该企业所拥有组织资源的 fine-grained personal access token 进行审批。
Fine-grained personal access tokens 限制

Fine-grained personal access tokens 不支持 personal access tokens (classic) 的所有功能。 这些功能差距不是永久性的 - GitHub 正在努力关闭它们。 可以查看我们的公开路线图，以了解何时会支持这些场景的更多详细信息。

fine-grained personal access token 的主要局限性包括：

  • 使用 fine-grained personal access token 向用户非成员的公共存储库提交代码。

  • 使用 fine-grained personal access token 向用户为外部用户或存储库协作者身份的存储库提交代码。

  • 使用 fine-grained personal access token 同时访问多个组织。

  • 使用 fine-grained personal access token 访问用户所在企业的 internal 资源。

  • 使用 fine-grained personal access token 调用用于管理企业帐户的 API。

  • 使用 fine-grained personal access token 访问包。

  • 使用 fine-grained personal access token 调用检查 API。

  • 使用 fine-grained personal access token 来访问由用户帐户拥有的项目。

所有这些差距将在一段时间内得到解决，因为 GitHub 将继续投资于更安全的访问模式。

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，请参阅该终结点的文档，或参阅“可用于细粒度的个人访问令牌的终结点”。

如果选择使用 a personal access token (classic)，请记住，它将授予对你有权访问的组织内的所有存储库以及个人帐户中的所有个人存储库的访问权限。

作为安全预防措施，GitHub 会自动删除一年内未使用过的 personal access token。 为了提供进一步的安全性，强烈建议将过期时间添加到 personal access token。

确保 personal access token 的安全性

Personal access tokens 类似于密码，它们共享相同的固有安全风险。 在创建新的 personal access 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 tokens 上限为 50。 如果您需要更多令牌或正在构建自动化，请考虑使用 GitHub App 以实现更好的可伸缩性和管理。 有关详细信息，请参阅“决定何时生成GitHub应用”。

  1. 验证电子邮件地址（如果尚未验证）。

  2. 在 GitHub 任意页面的右上角，单击你的个人资料照片，然后单击“ Settings”****。

  3. 在左边栏中，单击 “Developer settings”****。

  4. 在左侧边栏的 Personal access tokens 下，点击精细化令牌。

  5. 单击“生成新令牌”。

  6. 在“令牌名称”**** 下，输入令牌的名称。

  7. 在“过期时间”**** 下，选择令牌的过期时间。 允许永久有效，但可能会被组织或企业所有者设置的最长有效期策略阻止。 有关详细信息，请参阅 强制实施最长生存期策略 personal access tokens。

  8. （可选）在“描述”**** 下，添加备注说明令牌的用途。

  9. 在“资源所有者”**** 下，选择资源所有者。 令牌只能访问所选资源所有者拥有的资源。 你所属的组织如果阻止了对fine-grained personal access token 的使用，将不会被显示。 有关详细信息，请参阅 为组织设置个人访问令牌策略。 如果所选组织要求单一登录 (SSO)，且您当前没有有效的会话，则可能需要执行单一登录。

  10. （可选）如果资源所有者是需要对fine-grained personal access token进行批准的组织，请在资源所有者下方的框中输入请求理由。

  11. 在“存储库访问权限”**** 下，选择希望令牌访问的存储库。 应选择满足需求的最小存储库访问权限。 令牌始终包括对GitHub上所有公共存储库的只读访问权限。

  12. 如果上一步选择了“仅选定的存储库”，在“选定的存储库” 下拉菜单中，选择希望令牌访问的存储库。

  13. 在“权限”**** 下，选择要授予令牌的权限。 根据指定的资源所有者和存储库访问权限，有存储库、组织和帐户权限这几种可能性。 应根据需要选择最小权限。

    每个终结点的 REST API 参考文档都说明终结点是否支持 fine-grained personal access token，并说明令牌需要符合哪些权限才能使用该终结点。 某些终结点可能需要多个权限，而某些终结点可能需要多个权限之一。 有关 fine-grained personal access token 可以在每个权限下访问哪些 REST API 终结点的概述，请参阅 细粒度个人访问令牌所需的权限。

  14. 单击“生成令牌”。****

如果您选择了一个组织作为资源所有者，且该组织要求对 fine-grained personal access token 进行审批，那么您的令牌将被标记为 pending，直到组织管理员审核通过。 令牌在得到批准之前只能读取公共资源。 如果你是组织的所有者，请求将自动获得批准。 有关详细信息，请参阅“查看和撤销组织中的个人访问令牌”。

创建 personal access token (classic)

注意

组织所有者可以限制 personal access token (classic) 对其组织的访问。 如果尝试使用 a 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. 验证电子邮件地址（如果尚未验证）。
  2. 在 GitHub 任意页面的右上角，单击你的个人资料照片，然后单击“ Settings”****。
  3. 在左边栏中，单击 “Developer settings”****。
  4. 在左侧边栏的**Personal access token项下，单击令牌（经典）**。
  5. 选择“生成新令牌”，然后单击“生成新令牌（经典）”。
  6. 在“备注”字段中，为令牌提供一个描述性名称。
  7. 要为令牌设置过期时间，请选择“过期时间”，然后选择默认选项或单击“自定义” 输入日期。
  8. 选择要授予此令牌的作用域。 要使用令牌从命令行访问存储库，请选择“repo”****。 没有指定范围的令牌只能访问公共信息。 有关详细信息，请参阅“OAuth 应用的范围”。
  9. 单击“生成令牌”。****
  10. （可选）若要将新令牌复制到剪贴板，请单击 。

“Personal access tokens”页面的截图。 在模糊标记旁边，两个重叠方块的图标以橙色显示。

  1. 要使用令牌访问使用 SAML 单一登录的组织所拥有的资源，请对令牌进行授权。 有关详细信息，请参阅文档中的

删除 personal access token

如果不再需要，您应该删除 personal access token。 如果删除用于创建部署密钥的密钥 personal access token ，则也会删除部署密钥。

  1. 在 GitHub 任意页面的右上角，单击你的个人资料照片，然后单击“ Settings”****。
  2. 在左边栏中，单击 “Developer settings”****。
  3. 在左侧边栏的标签下，单击细粒度令牌或令牌（经典），具体取决于您要删除的的类型。
  4. 在要删除的 personal access token 右侧，单击“ 删除”。

[!NOTE] 如果发现属于其他人的 personal access token 泄漏，可以通过 REST API 提交吊销请求。 请参阅“防止组织中数据泄露的最佳做法”。

在命令行上使用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，但用户名并不用于身份验证。 相反，personal access token 用于对您的身份进行验证。 如果不输入用户名，会收到凭据无效的错误消息。

Personal access tokens 只能用于 HTTPS Git 操作。 如果存储库使用 SSH 远程 URL，则需要将远程 URL 从 SSH 切换到 HTTPS。

如果没有提示你输入用户名和密码，说明你的凭据可能已缓存在计算机上。 可在密钥链中更新凭据，从而用令牌替换旧密码。

您无需在每次 HTTPS Git 操作中手动输入 personal access token，而是可以使用 Git 客户端缓存您的 personal access token。 Git 会将你的凭据临时存储在内存中，直到过期为止。 你还可以将令牌存储在 Git 可以在每个请求之前读取的纯文本文件中。 有关详细信息，请参阅“在 Git 中缓存GitHub凭据”。

其他阅读材料