个人访问令牌

个人访问令牌可以替代 OAuth2 并用于：

  • 使用极狐GitLab API 进行身份验证。
  • 使用 HTTP 基本身份验证与 Git 进行身份验证。

在这两种情况下，您都使用个人访问令牌代替密码进行身份验证。用户名不作为

个人访问令牌是：

  • 启用双重身份验证（2FA）时需要。
  • 与极狐GitLab 用户名一起使用，需要用户名的功能可以进行身份验证。例如，极狐GitLab 管理的 Terraform 状态后端和 Docker container registry，
  • 类似于项目访问令牌，但附加到用户而不是项目或群组。
note 尽管是必需的，但在使用个人访问令牌进行身份验证时，会忽略极狐GitLab 用户名。

关于何如使用个人访问令牌进行身份验证，请参阅 API 文档。

相对地，管理员可以使用 API 创建 身份代理令牌。使用身份代理令牌自动化身份验证为特定用户。

创建个人访问令牌

  • 引入于 15.3 版本，UI 中填入了默认到期时间 30 天。
  • 创建不过期的个人访问令牌的功能删除于 16.0 版本。
  • 最大可允许的时间限制在极狐GitLab 17.6 中扩展到 400 天，使用名为 buffered_token_expiration_limit 的功能标志。默认禁用。
扩展的最大允许的时间限制功能的可用性由功能标志控制。更多详情，可查看历史。
caution 创建没有过期日期的个人令牌功能在极狐GitLab 15.4 中被弃用，在 16.0 中被删除。关于个人访问令牌到期及添加到现有令牌的过期日期，请参阅访问令牌过期。

您可以根据需要创建任意数量的个人访问令牌。

  1. 在左侧导航栏，选择您的头像。
  2. 选择 编辑个人资料。
  3. 在左侧边栏中，选择 访问令牌。
  4. 选择 添加新个人访问令牌。
  5. 输入个人访问令牌名称和到期日期。
    • 个人访问令牌到期日期为 UTC 时间的午夜。过期日期为 2024-01-01 的令牌在 2024-01-01 00:00:00 UTC 过期。
    • 如果您没有输入过期日期，则过期日期会自动设置为当前时间之后的 365 天。
    • 默认情况下，日期的最大值可以是当前日期的365天后。在极狐GitLab 17.6 或更高版本中，你可以扩展此限制至400天。
  6. 选择期望的范围。
  7. 选择 创建个人访问令牌。

将个人访问令牌安全保存。在您离开页面后，您将无法访问该令牌。

预填充个人访问令牌名称和范围

您可以直接链接到个人访问令牌页面，并在表单中预先填写名称和范围列表。为此，您可以向 URL 附加一个 name 参数和以逗号分隔的范围列表。例如：

https://gitlab.example.com/-/profile/personal_access_tokens?name=Example+Access+token&scopes=api,read_user,read_registry
caution 必须谨慎对待个人访问令牌。

撤销或轮换个人访问令牌

您可以随时撤销或轮换个人访问令牌：

  1. 在做的导航栏，选择您的头像。
  2. 选择 编辑个人资料。
  3. 在左侧边栏中，选择 访问令牌。

  4. 在 有效的个人访问令牌 区域，在密钥旁边，选择 撤销。

    caution 这些操作无法被撤销。依赖于撤销或轮换访问令牌的工具将停止工作。

禁用个人访问令牌

先决条件：

  • 您必须是管理员。

根据您的极狐GitLab 版本，您可以使用应用程序设置 API 或管理员 UI 禁用个人访问令牌。

使用应用程序设置 API

  • 引入于极狐GitLab 15.7。

在极狐GitLab 15.7 及更高版本中，您可以使用应用程序设置 API 中的 disable_personal_access_tokens 属性来禁用个人访问令牌。

note 在您已经使用 API 禁用个人访问令牌后，在后续的 API 调用中就没法使用这些令牌管理这些设置了。要重新启用个人访问令牌，请使用极狐GitLab Rails 控制台。您还可以升级到极狐GitLab 17.3 或更高版本，以便使用 Admin UI。

使用管理员 UI

  • 引入于极狐GitLab 17.3。

在极狐GitLab 17.3 及更高版本中，您可以使用管理员 UI 禁用个人访问令牌：

  1. 在左侧边栏中，在底部，选择 管理员。
  2. 选择 设置 > 通用。
  3. 扩展 可见性和访问控制。
  4. 选择 禁用个人访问令牌 复选框。
  5. 选择 保存更改。

为企业用户禁用个人访问令牌

  • 引入于极狐GitLab 16.11，使用名为 enterprise_disable_personal_access_tokens 的功能标志。默认禁用。
  • 在极狐GitLab 17.2 中为 JihuLab.com 启用。
  • 在极狐GitLab 17.3 中 GA，功能标志 enterprise_disable_personal_access_tokens 被移除。

先决条件：

  • 您必须是企业用户所属群组的所有者。

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

  • 停止企业用户创建新个人访问令牌。这种行为适用于企业用户同时也是群组的管理员。
  • 禁用企业用户的现有个人访问令牌。
note 为企业用户禁用个人访问令牌的功能不会禁用服务账户的个人访问令牌。

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

  1. 在左侧导航栏，选择 搜索或前往 并找到您的群组或子群组。
  2. 选择 设置 > 通用。
  3. 扩展 权限和群组特性。
  4. 在 个人访问令牌 区域，选择 禁用个人访问令牌。
  5. 选择 保存更改。

查看上次使用令牌的时间

  • 在极狐GitLab 16.0 及更早版本中，令牌使用信息每天更新一次。
  • 令牌使用信息在 16.1 中的更新频率从每天更新到每 10 分钟更新。

令牌使用信息每隔十分钟更新一次。发行如下情况，极狐GitLab 会认为令牌被使用：

查看上次使用令牌的时间：

  1. 在右上角，选择您的头像。
  2. 选择 编辑个人资料。
  3. 在左侧边栏中，选择 访问令牌。
  4. 在 有效的个人访问令牌 区域，在密钥旁边，查看 最近使用 日期。

个人访问令牌范围

  • 在极狐GitLab 16.0 中，个人访问令牌将不再能够访问容器镜像库或软件包库。
  • k8s_proxy 引入于极狐GitLab 16.4，使用名为 k8s_proxy_pat 的功能标志。默认启用。
  • 在极狐GitLab 16.5 中，功能标志 k8s_proxy_pat 被移除。
  • read_service_ping 引入于极狐GitLab 17.1。
  • manage_runner 引入于极狐GitLab 17.1。

个人访问令牌不再能够访问容器镜像库或软件包库于 16.0 版本。

个人访问令牌可以根据分配的范围执行操作。

范围 访问
api 完整 API 读写，包括所有群组和项目、容器镜像库和软件包库。
read_user /users 下的端点只读。本质上，访问 中的任何 GET 请求。
read_api 完整 API 只读，包括所有群组和项目、容器镜像库和软件包库。（引入于 13.10 版本）
read_repository 通过 git clone 对仓库进行只读（拉取）。
write_repository 通过 git clone 对仓库进行读写（拉取、推送）。
read_registry 如果项目是私有的并且需要授权，则 Container Registry 镜像只读（拉取）。仅当 Container Registry 启用时适用。
write_registry 如果项目是私有的并且需要授权，则对 Container Registry 镜像进行读写（推送）。仅当 Container Registry 启用时适用。（引入于 13.10 版本）
sudo 作为系统中任何用户的 API 操作（如果经过身份验证的用户是管理员）。
admin_mode 当启用管理员模式时，作为管理员为执行 API 操作授权。（引入于极狐GitLab 15.8。仅针对私有化部署版本。）
create_runner 为创建 runner 授权。
manage_runner 为管理 runner 授权。
k8s_proxy 授权使用 Kubernetes agent 来执行 Kubernetes API 调用。
read_service_ping 当认证为管理员时，授权通过 API 来下载 Ping payload。
caution 如果启用了外部授权，个人访问令牌无法访问容器镜像库或软件包库。如果您使用个人访问令牌访问它们，系统会中断对这些令牌的使用。禁用外部授权可以将个人访问令牌用于容器镜像库或软件包库。

访问令牌过期

  • 最大可允许的时间限制在极狐GitLab 17.6 中扩展到 400 天，使用名为 buffered_token_expiration_limit 的功能标志。默认禁用。
扩展的最大允许的时间限制功能的可用性由功能标志控制。更多详情，可查看历史。

个人访问令牌在您定义的日期过期，在 00:00 AM UTC。具有过期日期的个人访问令牌的过期日是 2024-01-01，则会在 2024-01-01 的 00:00:00 UTC 过期。

  • 极狐GitLab 会在每天的 1:00 AM UTC 运行检查以识别快要过期的个人访问令牌。这些令牌会通过邮件进行通知。
  • 极狐GitLab 会在每天的 2:00 AM UTC 运行检查以识别在当天过期的个人访问令牌。这些令牌的所有者会通过邮件进行通知。
  • 在极狐GitLab 专业版中，管理员可以限制个人访问令牌的可用时间。如果未设置，最大允许的个人访问令牌的可用时间为 365 天。在极狐GitLab 17.6 或更晚的版本中，您可以扩展此限制到 400 天。
  • 在极狐GitLab 免费和专业版中，最大允许的个人访问令牌的可用时间为 365 天。在极狐GitLab 17.6 或更晚的版本中，您可以扩展此限制到 400 天。
  • 如果您在创建个人访问令牌时未设置过期日期，过期日期将设置为允许的最大可用时间。如果允许的最大可用时间未设置，默认日期为创建日期之后的 365 天。

你现有的个人访问令牌是否会自动设置过期日期，这取决于你所使用的极狐GitLab 服务套餐，以及您是在何时升级到极狐GitLab 16.0 或更高版本的：

  • 在极狐GitLab 16.0 期间，没有过期日期的既有个人访问令牌会被自动设定为一个 365 天的过期日期。
  • 在极狐GitLab 私有化部署实例上，如果您从极狐GitLab 15.11 或更早的版本升级到 16.0 或更高版本，您的现有个人访问令牌将自动设定为一个 365 天的过期日期。
    • 在 2024 年 7 月 23 日之前，您的现有个人访问令牌将自动设定为一个 365 天的过期日期。 这是一个破坏性的更改。
    • 在 2024 年 7 月 24 日之后，您的现有个人访问令牌将不会设定过期日期。

在极狐GitLab 私有化部署版本中，如果您从下面的任何一个极狐GitLab 版本进行新安装，您的现有个人访问令牌不会自动设定过期日期：

  • 16.0.9
  • 16.1.7
  • 16.2.10
  • 16.3.8
  • 16.4.6
  • 16.5.9
  • 16.6.9
  • 16.7.9
  • 16.8.9
  • 16.9.10
  • 16.10.9
  • 16.11.7
  • 17.0.5
  • 17.1.3
  • 17.2.1

个人访问令牌过期通知邮件

  • 60 天和 30 天过期通知邮件在 GitLab 17.6 中引入，使用名为 expiring_pats_30d_60d_notifications 的功能标志。默认禁用。
60 天和 30 天过期邮件通知的可用性受控于功能标志。更多详情，可查看历史。

极狐GitLab 会在每天的 1:00 AM UTC 运行检查以识别个人访问令牌过期的个数。这些个人访问令牌的所有者会在过期的天数不同的情况下通过邮件进行通知：

  • 在极狐GitLab 17.6 或更晚的版本中，当检查识别到个人访问令牌将在接下来 60 天过期时，会通过邮件通知个人访问令牌的所有者。
  • 当检查识别到个人访问令牌将在接下来 30 天过期时，会通过邮件通知个人访问令牌的所有者。

创建一个没有过期日期的服务账号个人访问令牌

您可以为服务账号创建一个个人访问令牌，它们永不过期，与非服务帐户个人访问令牌不同。

note 允许为服务账号创建没有过期日期的个人访问令牌仅会影响您修改此设置后创建的令牌。它不会影响既有令牌。

JihuLab.com

先决条件：

  • 您必须是顶级群组的所有者角色。
  1. 在左侧导航栏，选择 搜索或前往 并找到您的群组。
  2. 选择 设置 > 通用 > 访问权限和群组特性。
  3. 清除 服务帐户令牌到期 复选框。

您可以现在为服务帐户用户创建个人访问令牌，没有到期日期。

私有化部署的极狐GitLab

先决条件：

  • 您必须是极狐GitLab 私有化部署实例的管理员。
  1. 在左侧导航栏，在底部，选择 管理员。
  2. 选择 设置 > 通用。
  3. 展开 帐户和限制。
  4. 清除 服务帐户令牌到期 复选框。

您可以现在为服务帐户用户创建个人访问令牌，没有到期日期。

通过编程的方式创建个人访问令牌

您可以使用编程的方式来创建预定义的个人访问令牌，以便在测试或自动化中使用。

先决条件：

要通过编程的方式创建个人访问令牌：

  1. 打开 Rails 控制台：

    sudo gitlab-rails console

  2. 使用如下命令来引用用户名，令牌和权限：

    令牌必须是 20 个字符长。权限必须是有效的并且在源代码中可见。

    比如，为 automation-bot 用户创建一个在一年内过期的令牌：

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

此代码已经通过使用 Rails Runner简化为单行 shell 命令:

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

用编程的方式来撤销个人访问令牌 (BSIC ALL)

您可以通过编程的俄方来撤销个人访问令牌。

先决条件：

要用编程的方式撤销令牌：

  1. 打开 Rails 控制台：

    sudo gitlab-rails console

  2. 要撤销名为 token-string-here123 的令牌，运行下面的命令：

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

此代码已经通过使用 Rails Runner简化为单行 shell 命令:

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

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

当 SSH 禁用时，您可以使用个人访问令牌克隆仓库：

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

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

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

当询问您的 https://jihulab.com 密码时，请输入您的个人访问令牌。

clone 命令中的 username： - 可能是任意字符串值。 - 不能为空字符串。

如果您设置了依赖于身份验证的自动化流水线，请记住这一点，

故障排除

取消撤销个人访问令牌

如果个人访问令牌被任何方法意外撤销，管理员可以取消撤销该令牌。默认情况下，每日作业会在系统时间凌晨 1:00 删除已撤销的令牌。

caution 运行以下命令直接更改数据。无论操作是否正确，都可能会造成损害。您应该首先在测试环境中运行这些命令，并准备好要恢复的实例备份，以防万一。
  1. 打开 Rails 控制台。

  2. 撤销令牌：

    token = PersonalAccessToken.find_by_token('<token_string>')
token.update!(revoked:false)

    例如，取消撤销 token-string-here123 的令牌：

    token = PersonalAccessToken.find_by_token('token-string-here123')
token.update!(revoked:false)

个人访问令牌的替代品

对于基于 Git over HTTPS，个人访问令牌的替代方法是 Oauth 凭据 helper。