个人访问令牌

个人访问令牌为极狐GitLab 提供认证访问。它们是 OAuth2 令牌 的替代方案， 类似于群组访问令牌和项目访问令牌，但附加到用户而非群组或项目。

你可以使用个人访问令牌进行认证：

• 通过 极狐GitLab API。
• 通过 Git over HTTPS。使用时：
  • 任意非空值作为用户名。
  • 个人访问令牌作为密码。

部分需要用户名的极狐GitLab 功能，例如 极狐GitLab 托管 Terraform 状态后端 和 容器镜像仓库， 使用带有极狐GitLab 用户名的个人访问令牌。在这些情况下，用户名是必需的， 但不会作为认证的一部分进行评估。更多信息请参见 issue 212953。

在私有化部署实例上，管理员可以使用 用户令牌 API 创建模拟令牌以特定用户身份进行认证。

查看令牌使用信息#

版本历史

• 在极狐GitLab 16.0 及更早版本中，令牌使用信息每 24 小时更新一次。
• 令牌使用信息更新的频率在极狐GitLab 16.1 变更 为从 24 小时缩短至 10 分钟。
• 查看 IP 地址功能在极狐GitLab 17.8 引入 通过一个功能标志 名为 pat_ip。默认在 17.9 中启用。
• 查看 IP 地址功能在极狐GitLab 17.10 GA。功能标志 pat_ip 已移除。

个人访问令牌页面显示有关你的访问令牌的信息。

在此页面，你可以执行以下操作：

• 创建、轮换和吊销个人访问令牌。
• 查看所有活跃和非活跃的个人访问令牌。
• 查看令牌信息，包括范围、指派的角色和过期日期。
• 查看使用信息，包括使用日期和最后五个不同连接 IP 地址。
  当令牌执行 Git 操作或通过REST 或 GraphQL API 认证操作时，极狐GitLab 会定期更新令牌使用信息。令牌使用时间每 10 分钟更新一次，令牌使用 IP 地址每分钟更新一次。

要查看你的个人访问令牌：

1. 在右上角，选择你的头像。
2. 选择 编辑个人资料。
3. 在左侧边栏中，选择 访问 > 个人访问令牌。

选择令牌名称以打开详细信息面板。默认情况下，仅显示活跃令牌。 使用搜索栏过滤访问令牌列表。

创建个人访问令牌#

版本历史

• 创建永久个人访问令牌的功能在极狐GitLab 16.0 中已移除。
• 最大允许的有效期限制在极狐GitLab 17.6 中延长至 400 天 通过一个功能标志 名为 buffered_token_expiration_limit。默认禁用。
• 个人访问令牌描述在极狐GitLab 17.7 中引入。

要创建个人访问令牌：

1. 在右上角，选择你的头像。
2. 选择 编辑个人资料。
3. 在左侧边栏中，选择 访问 > 个人访问令牌。
4. 从 生成令牌 下拉列表中，选择 旧版令牌。
5. 在 令牌名称 中，输入令牌名称。
6. 可选。在 令牌描述 中，输入令牌描述。
7. 在 过期日期 中，输入令牌的过期日期。
   • 令牌在该日期的 UTC 午夜过期。
   • 如果你未输入日期，过期日期将设置为自今日起 365 天后。
   • 默认情况下，过期日期不能超过自今日起 365 天。在极狐GitLab 17.6 及更高版本中，管理员可以修改访问令牌的最大有效期。
8. 选择一个或多个 个人访问令牌范围。
9. 选择 生成令牌。

将显示个人访问令牌。请将个人访问令牌保存在安全的地方。离开或刷新页面后，你将无法再次查看它。

所有访问令牌都继承 为个人访问令牌配置的 默认前缀设置。

预填个人访问令牌详情#

你可以通过将名称、描述和范围列表附加到 URL 来预填个人访问令牌的详细信息。例如：

plaintext
https://gitlab.example.com/-/user_settings/personal_access_tokens?name=Example+Access+token&description=My+description&scopes=api,read_user

个人访问令牌范围#

版本历史

• 个人访问令牌不再能够访问容器或软件包仓库在极狐GitLab 16.0 中引入。
• k8s_proxy 在极狐GitLab 16.4 中引入 通过一个功能标志 名为 k8s_proxy_pat。默认启用。
• 功能标志 k8s_proxy_pat 在极狐GitLab 16.5 中已移除。
• read_service_ping 在极狐GitLab 17.1 中引入。
• manage_runner 在极狐GitLab 17.1 中引入。
• self_rotate 在极狐GitLab 17.9 中引入。默认启用。

范围定义了使用个人访问令牌认证时可用的操作。以下是可用的范围：

轮换个人访问令牌#

版本历史

• 使用 UI 轮换个人访问令牌的功能在极狐GitLab 17.7 中引入。
• 更新 UI 在极狐GitLab 18.1 中。

轮换令牌以创建一个与原始令牌具有相同权限和范围的新令牌。 原始令牌立即变为非活跃状态，极狐GitLab 将保留两个版本以供审计。

要轮换个人访问令牌：

1. 在右上角，选择你的头像。
2. 选择 编辑个人资料。
3. 在左侧边栏中，选择 访问 > 个人访问令牌。
4. 在活跃令牌旁边，选择垂直省略号 (
   )。
5. 选择 轮换 (
   )。
6. 在确认对话框中，选择 轮换。

吊销个人访问令牌#

版本历史

• 更新 UI 在极狐GitLab 18.1 中。

吊销令牌以立即使其失效并阻止进一步使用。极狐GitLab 将保留令牌以供审计目的。你无法永久删除令牌，但可以过滤令牌列表以仅显示活跃令牌。

要吊销个人访问令牌：

1. 在右上角，选择你的头像。
2. 选择 编辑个人资料。
3. 在左侧边栏中，选择 访问 > 个人访问令牌。
4. 在活跃令牌旁边，选择垂直省略号 (
   )。
5. 选择 吊销 (
   )。
6. 在确认对话框中，选择 吊销。

访问令牌过期#

个人、群组和项目访问令牌在过期日期的 UTC 午夜过期。 过期后，它们将无法再用于认证请求。

在极狐GitLab 16.0 及更高版本中，新访问令牌必须具有过期日期。如果在创建令牌时未明确设置过期日期，将应用自当前日期起 365 天的过期日期。 在极狐GitLab 旗舰版中，管理员可以为访问令牌配置 最大允许有效期。

根据你的极狐GitLab 版本和许可证类型，升级极狐GitLab 版本时，你现有的访问令牌可能会自动应用过期日期。更多信息， 请参见 非过期访问令牌。

个人访问令牌过期邮件#

版本历史

• 60 天和 30 天过期通知在极狐GitLab 17.6 中引入 通过一个功能标志 名为 expiring_pats_30d_60d_notifications。默认禁用。
• 60 天和 30 天通知在极狐GitLab 17.7 中GA。功能标志 expiring_pats_30d_60d_notifications 已移除。

极狐GitLab 每天 UTC 时间凌晨 1:00 运行一个检查，以识别即将过期的个人访问令牌。 在令牌过期前 7 天，用户会通过电子邮件收到通知。在极狐GitLab 17.6 及更高版本中，还将在令牌过期前 30 天和 60 天发送通知。

个人访问令牌过期日历#

你可以订阅一个 iCalendar 端点，其中包含每个令牌过期日期的事件。登录后，此端点可在 /-/user_settings/personal_access_tokens.ics 获取。

创建不过期的服务账户个人访问令牌#

你可以为服务账户创建个人访问令牌 且不设置过期日期。与非服务账户个人访问令牌不同，这些个人访问令牌永不过期。

JihuLab.com#

先决条件：

• 你必须对顶级群组具有所有者角色。

1. 在顶部栏中，选择 搜索或跳转到 并找到你的群组。
2. 在左侧边栏中，选择 设置 > 通用。
3. 展开 权限和群组功能。
4. 在 个人访问令牌 下，清除 要求服务账户的过期日期 复选框。

你现在可以为服务账户用户创建不过期的个人访问令牌。

私有化部署#

先决条件：

• 你必须是你私有化部署实例的管理员。

1. 在右上角，选择 管理员。
2. 在左侧边栏中，选择 设置 > 通用。
3. 展开 账户和限制。
4. 清除 服务账户令牌过期 复选框。

你现在可以为服务账户用户创建不过期的个人访问令牌。

禁用访问令牌#

版本历史

• 禁用访问令牌 设置 引入 在极狐GitLab 17.3。

先决条件：

• 管理员访问权限。

你可以防止用户在整个极狐GitLab 实例中使用访问令牌进行认证。此设置会影响个人访问令牌、群组访问令牌、项目访问令牌和模拟令牌。此设置也适用于服务账户的个人访问令牌。

当你禁用访问令牌时，以下规则适用：

• 用户无法使用个人访问令牌登录极狐GitLab。
• 个人访问令牌页面返回 404 Not Found 错误。
• RSS、Atom 和日历订阅的订阅令牌停止工作。
• 使用个人访问令牌认证的 API 请求将被拒绝。

要为实例禁用访问令牌：

1. 在右上角，选择 管理员。
2. 在左侧边栏中，选择 设置 > 通用。
3. 展开 账户和限制。
4. 选中 禁用访问令牌 复选框。
5. 选择 保存更改。

你还可以在应用设置 API 中使用 disable_personal_access_tokens 属性。

禁止企业用户使用个人访问令牌#

版本历史

• 引入 在极狐GitLab 16.11 通过一个功能标志 名为 enterprise_disable_personal_access_tokens。默认禁用。
• 在 JihuLab.com 上启用 在极狐GitLab 17.2。
• GA 在极狐GitLab 17.3。功能标志 enterprise_disable_personal_access_tokens 已移除。

先决条件：

• 对用户所属群组具有所有者角色。

禁止群组的企业用户 的个人访问令牌：

• 阻止企业用户创建新的个人访问令牌。即使企业用户同时也是群组管理员，此行为也适用。
• 禁用企业用户现有的个人访问令牌。

要禁止企业用户的个人访问令牌：

1. 在顶部栏中，选择 搜索或跳转到 并找到你的群组。
2. 在左侧边栏中，选择 设置 > 通用。
3. 展开 权限和群组功能。
4. 在 企业用户 下，选择 禁用个人访问令牌。
5. 选择 保存更改。

当你删除或阻止企业用户账户时，其个人访问令牌将自动吊销。

以编程方式创建个人访问令牌#

你可以创建预定的个人访问令牌，作为测试或自动化的一部分。

先决条件：

• 你需要足够的访问权限来为你的极狐GitLab 实例运行 Rails 控制台会话。

要以编程方式创建个人访问令牌：

1. 打开 Rails 控制台：

   shell
   sudo gitlab-rails console

2. 运行以下命令以引用用户名、令牌和范围。

   令牌长度必须为 20 个字符。范围必须有效，并可在 源代码 中查看。

   例如，要创建一个属于用户名为 automation-bot 的用户且一年后过期的令牌：

   ruby
   user = User.find_by_username('automation-bot')
   token = user.personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: '自动化令牌', expires_at: 365.days.from_now)
   token.set_token('token-string-here123')
   token.save!

此代码可以通过使用 Rails runner 缩短为单行 shell 命令：

shell
sudo gitlab-rails runner "token = User.find_by_username('automation-bot').personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: '自动化令牌', expires_at: 365.days.from_now); token.set_token('token-string-here123'); token.save!"

以编程方式吊销个人访问令牌#

你可以以编程方式吊销个人访问令牌，作为测试或自动化的一部分。

先决条件：

• 你需要足够的访问权限来为你的极狐GitLab 实例运行 Rails 控制台会话。

要以编程方式吊销令牌：

1. 打开 Rails 控制台：

   shell
   sudo gitlab-rails console

2. 要吊销 token-string-here123 的令牌，请运行以下命令：

   ruby
   token = PersonalAccessToken.find_by_token('token-string-here123')
   token.revoke!

   ruby
   token = PersonalAccessToken.find_by_token('token-string-here123')
   token.revoke!

这段代码可以通过 Rails runner 简化为一行 shell 命令：

shell
sudo gitlab-rails runner "PersonalAccessToken.find_by_token('token-string-here123').revoke!"

使用个人访问令牌克隆仓库#

要在 SSH 被禁用时使用个人访问令牌克隆仓库，请运行以下命令：

shell
git clone https://<username>:<personal_token>@jihulab.com/gitlab-org/gitlab.git

此方法会将您的个人访问令牌保存在 bash 历史记录中。为避免这种情况，请运行以下命令：

shell
git clone https://<username>@jihulab.com/gitlab-org/gitlab.git

当系统要求您输入 https://jihulab.com 的密码时，输入您的个人访问令牌。

clone 命令中的 username：

• 可以是任意字符串。
• 不能为空字符串。

如果您设置了依赖认证的自动化流水线，请务必记住这一点。

个人访问令牌的替代方案#

对于通过 HTTPS 访问 Git，个人访问令牌的一种替代方案是使用 OAuth 凭据助手。

对于 CI/CD 作业中的认证，请考虑：

• 使用 CI/CD 作业令牌并结合细粒度权限，进行流水线认证。
• 使用具有项目特定自动化所需最小权限的项目访问令牌。

相关主题#

• 群组访问令牌
• 项目访问令牌
• 个人访问令牌 API
• 支持细粒度个人访问令牌的 REST API 端点