管理个人访问令牌

警告

将访问令牌视为密码一样保管。有关详细信息，请参阅保护你的 personal access token。

关于 personal access token

使用 GitHub API 或命令行时，Personal access token 是替代密码对 GitHub 进行身份验证的方式。

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

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

确保 personal access token 安全

Personal access token 类似于密码，它们具有相同的固有安全风险。创建新的 personal access token 之前，请考虑是否有更安全的身份验证方法可供使用：

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

如果无法使用这些选项，但必须创建 personal access token，请考虑使用其他 CLI 服务安全地存储令牌。

在脚本中使用 personal access token 时，可以将令牌存储为机密，并通过 GitHub Actions 运行脚本。有关详细信息，请参阅在 GitHub Actions 中使用机密。

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

创建 fine-grained personal access token

注意

最多可以创建 50 个fine-grained personal access tokens。如果需要更多令牌或打算生成自动化，请考虑使用 GitHub App 来提高可伸缩性并进行更好的管理。有关详细信息，请参阅“决定何时生成 GitHub 应用”。

在 GitHub 任意页面的右上角，单击你的个人资料照片，然后单击“ Settings”****。
在左边栏中，单击 “Developer settings”****。
在左边栏的“ Personal access token”下，单击“Fine-grained tokens”********。
单击“生成新令牌”****。
在“令牌名称”**** 下，输入令牌的名称。
在“过期时间”**** 下，选择令牌的过期时间。允许永久有效，但可能会被组织或企业所有者设置的最长有效期策略阻止。有关详细信息，请参阅为 personal access tokens 强制执行最长有效期策略。
（可选）在“描述”**** 下，添加备注说明令牌的用途。
在“资源所有者”**** 下，选择资源所有者。令牌只能访问所选资源所有者拥有的资源。如果你所属的组织已阻止使用 fine-grained personal access token，那么该组织将不会显示。有关详细信息，请参阅“为组织设置个人访问令牌策略”。
（可选）如果资源所有者是需要批准 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，直到组织管理员审核为止。令牌在得到批准之前只能读取公共资源。如果你是组织的所有者，请求将自动获得批准。有关详细信息，请参阅“查看和撤销组织中的个人访问令牌”。

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

可以通过链接共享 fine-grained personal access token 的模板。通过这种方式存储令牌详细信息，能更轻松地实现工作流自动化；同时，引导用户进入令牌创建流程时相关字段已预先填写，进而可优化开发人员体验。

可使用特定查询参数设置每个受支持的字段。所有参数均为可选，且会通过令牌生成表单进行验证，以确保权限与资源所有者的组合合理有效。

此处展示了一个示例 URL 模板，为便于阅读添加了换行符：

HTTP

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 天。你会看到一条错误消息，指示由于你不是 octodemo 组织的成员，所以 Cannot find the specified resource owner: octodemo。

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

          [读取存储库内容](https://github.com/settings/personal-access-tokens/new?name=Repo-reading+token&description=Just+contents:read&contents=read)

          [对存储库的推送访问权限](https://github.com/settings/personal-access-tokens/new?name=Repo-writing+token&description=Just+contents:write&contents=write)

          [GitHub 模型访问权限](https://github.com/settings/personal-access-tokens/new?name=GitHub+Models+token&description=Used%20to%20call%20GitHub%20Models%20APIs%20to%20easily%20run%20LLMs%3A%20https%3A%2F%2Fdocs.github.com%2Fgithub-models%2Fquickstart%23step-2-make-an-api-call&user_models=read)<!-- markdownlint-disable-line search-replace Custom rule -->

          [更新代码并创建 PR](https://github.com/settings/personal-access-tokens/new?name=Core-loop+token&description=Write%20code%20and%20push%20it%20to%20main%21%20Includes%20permission%20to%20edit%20workflow%20files%20for%20Actions%20-%20remove%20%60workflows%3Awrite%60%20if%20you%20don%27t%20need%20to%20do%20that&contents=write&pull_requests=write&workflows=write)

          [管理组织中的 Copilot 许可证](https://github.com/settings/personal-access-tokens/new?name=Core-loop+token&description=Enable%20or%20disable%20copilot%20access%20for%20users%20with%20the%20Seat%20Management%20APIs%3A%20https%3A%2F%2Fdocs.github.com%2Frest%2Fcopilot%2Fcopilot-user-management%0ABe%20sure%20to%20select%20an%20organization%20for%20your%20resource%20owner%20below%21&organization_copilot_seat_management=write)<!-- markdownlint-disable-line search-replace Custom rule -->

        [发出 Copilot 请求](https://github.com/settings/personal-access-tokens/new?name=Copilot+requests+token&description=Make%20Copilot%20API%20requests%20on%20behalf%20of%20the%20user%2C%20consuming%20premium%20requests%3A%20https%3A%2F%2Fdocs.github.com%2Fcopilot%2Fconcepts%2Fbilling%2Fcopilot-requests&copilot_requests=write)<!-- markdownlint-disable-line search-replace Custom rule -->

支持的查询参数

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

参数	类型	示例值	有效值	说明
`name`	字符串	`Deploy%20Bot`	≤ 40 个字符，URL 编码	预填充令牌的显示名称。
`description`	字符串	`Used+for+deployments`	≤ 1024 个字符，URL 编码	预填充有关令牌的描述。
`target_name`	字符串	`octodemo`	用户或组织 slug	设置令牌的资源目标。这是令牌将能够访问的存储库的所有者。如果未提供，则默认为当前用户的帐户。
`expires_in`	整数	`30` 或 `none`	介于 1 到 366 之间的整数，或为 `none`	到期之前的剩余天数，若为永不过期则设为 `none`。如果未提供，默认值为 30 天，如果目标设置了令牌生存期策略，默认值更小。
`<permission>`	字符串	`contents=read`	一系列权限和访问级别。	令牌应具有的权限。权限可以设置为 `read`、`write` 或 `admin`，但并非每种权限都支持这些级别。

权限

每种支持的权限均通过使用其名称作为查询参数来进行设置，其值指定所需的访问级别。有效访问级别为 read、write 和 admin。一些权限仅支持 read，一些仅支持 write，只有少数具有 admin。根据需要使用任意数量的权限，并采用 &contents=read&pull_requests=write&... 形式。

无需在 URL 中为某个权限同时包含 read 和 write - write 始终包括 read，admin 始终包括 write。

帐户权限

仅当当前用户设置为资源所有者时，才使用帐户权限。

参数名称	显示名称	访问级别
`blocking`	阻止另一个用户

          `read`、`write` |

存储库权限

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

参数名称	显示名称	访问级别
`actions`	操作

          `read`、`write` |

组织权限

仅当资源所有者是组织时，才可使用组织权限。

参数名称	显示名称	访问级别
`organization_api_insights`	API 见解	`read`
`organization_administration`	管理

          `read`、`write` |

创建 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 还允许指定细粒度的权限，而不是宽泛的范围。

在 GitHub 任意页面的右上角，单击你的个人资料照片，然后单击“ Settings”****。
在左边栏中，单击 “Developer settings”****。
在左边栏的“ Personal access token”下，单击“Tokens (classic)”********。
选择“生成新令牌”，然后单击“生成新令牌（经典）”。
在“备注”字段中，为令牌提供一个描述性名称。
要为令牌设置过期时间，请选择“过期时间”，然后选择默认选项或单击“自定义” 输入日期。
选择要授予此令牌的作用域。要使用令牌从命令行访问存储库，请选择“repo”****。没有指定范围的令牌只能访问公共信息。有关详细信息，请参阅“OAuth 应用的范围”。
单击“生成令牌”。****
（可选）要将新令牌复制到剪贴板，请单击。

删除 personal access token

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

在 GitHub 任意页面的右上角，单击你的个人资料照片，然后单击“ Settings”。1. 在左边栏中，单击 “Developer settings”。
在左边栏的“ Personal access token”下，单击“Fine-grained tokens”或“Tokens (classic)”，具体取决于要删除哪种类型的 personal access token************。
在要删除的 personal access token 右侧，单击“删除”****。

在命令行上使用 personal access token

如果你有 personal access token，则可以在通过 HTTPS 执行 Git 操作时输入它，而不是密码。

例如，要在命令行上克隆存储库，请输入以下 git clone 命令。然后，系统会提示你输入用户名和密码。当系统提示输入密码时，请输入 personal access token 而不是密码。

$ git clone https://HOSTNAME/USERNAME/REPO.git
Username: YOUR-USERNAME
Password: YOUR-PERSONAL-ACCESS-TOKEN

虽然需要输入用户名和 personal access token，但用户名不用于身份验证。相反，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 凭据”。

其他阅读材料

          [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github)

          [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation)

本文内容