管理个人访问令牌

关于 personal access token

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

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 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身份验证之前，请考虑是否有更安全的身份验证方法可供你使用：

• 若要从命令行访问 GitHub ，可以使用 GitHub CLI 或 Git 凭据管理器 而不是创建 personal access token。
• 在 personal access token 工作流中使用 GitHub Actions 时，请考虑是否可以使用内置的 GITHUB_TOKEN 替代。 有关详细信息，请参阅“在工作流中使用 GITHUB_TOKEN 进行身份验证”。

如果这些选项不可行，并且您必须创建一个 personal access token，请考虑使用另一个 CLI 服务来安全地存储令牌。

在脚本中使用 personal access token 时，可以将令牌存储为机密信息，并通过 GitHub Actions 运行该脚本。 有关详细信息，请参阅 在 GitHub Actions 中使用机密。 还可以将令牌存储为 Codespaces 机密，并在 Codespaces 中运行脚本。 有关详细信息，请参阅 管理 GitHub Codespaces 的账户专属的机密。

有关最佳做法的详细信息，请参阅 确保 API 凭据安全。

创建 fine-grained personal access token

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，直到组织管理员审核通过。 令牌在得到批准之前只能读取公共资源。 如果你是组织的所有者，请求将自动获得批准。 有关详细信息，请参阅“查看和撤销组织中的个人访问令牌”。

使用 URL 参数预填充 fine-grained personal access token 详细信息

可以通过链接共享该模板 fine-grained personal access token 。 通过将用户引导至相关字段已预先填好的创建令牌页面，您可以更轻松地实现工作流自动化，并提升开发者体验。

可使用特定查询参数设置每个受支持的字段。 所有参数都是可选的，并由令牌生成表单验证，以确保权限和资源所有者的组合有意义。

下面是一个示例 URL 模板，其中包含用于可读性的换行符：

https://github.com/settings/personal-access-tokens/new
  ?name=Repo-reading+token
  &description=Just+contents:read
  &target_name=octodemo
  &expires_in=45
  &contents=read

https://github.com/settings/personal-access-tokens/new
  ?name=Repo-reading+token
  &description=Just+contents:read
  &target_name=octodemo
  &expires_in=45
  &contents=read

尝试使用此 URL 创建令牌，需包含 contents:read 和 metadata:read，并填写指定的名称与描述，且令牌过期时间设为未来 45 天。 你会看到一条错误消息，指示由于你不是 Cannot find the specified resource owner: octodemo 组织的成员，所以 octodemo。

下面是一些生成最常见令牌的示例 URL：

• 读取存储库内容
• 推送对存储库的访问权限
• GitHub Models访问
• 更新代码并打开拉取请求
• 管理 Copilot 组织中的许可证
• 发出 Copilot 请求

支持的查询参数

要创建自己的令牌模板，请按照下表中提供的查询参数详细信息操作：

权限

若要设置权限，请使用其名称作为查询参数，并指定所需的访问级别的值。 有效的访问级别包括 read、write 和 admin，但并非每项权限都支持每个级别——有些仅支持 read，有些仅支持 write，而且只有少数支持 admin。

将表单 &contents=read&pull_requests=write&...中的多个权限组合在一起，并根据需要使用任意数量的权限。

帐户权限

存储库权限

存储库权限同时适用于用户和组织资源所有者。

组织权限

创建 personal access token (classic)

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

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

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

4. 在左侧边栏的**Personal access token项下，单击令牌（经典）**。

5. 选择“生成新令牌”，然后单击“生成新令牌（经典）”。

6. 在“备注”字段中，为令牌提供一个描述性名称。

7. 要为令牌设置过期时间，请选择“过期时间”，然后选择默认选项或单击“自定义” 输入日期。

8. 选择要授予此令牌的作用域。 要使用令牌从命令行访问存储库，请选择“repo”****。 没有指定范围的令牌只能访问公共信息。 有关详细信息，请参阅“OAuth 应用的范围”。

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

10. （可选）若要将新令牌复制到剪贴板，请单击 。

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凭据”。

其他阅读材料

• 关于 GitHub 的身份验证
• 令牌过期和吊销