个人访问令牌

  • 引入于 12.6 版本:令牌到期通知。
  • 引入于旗舰版 12.6 版本:令牌生命周期限制。
  • 引入于 13.3 版本:令牌过期的附加通知。
  • 引入于 14.1 版本:预填充令牌名称和范围。

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

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

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

caution 在 15.4 版本中已弃用创建没有过期的个人访问令牌的功能,并计划在 16.0 版本中删除。删除此功能后,需要为无到期时间的现有个人访问令牌添加到期时间。

个人访问令牌是:

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

创建个人访问令牌

  • 引入于 15.3 版本,UI 中填入了默认到期时间 30 天。
  • 创建不过期的个人访问令牌的功能删除于 16.0 版本。

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

  1. 在右上角,选择您的头像。
  2. 选择 编辑个人资料
  3. 在左侧边栏中,选择 访问令牌
  4. 输入令牌的名称和到期日期。
    • 令牌在该日期的午夜 UTC 到期。
    • 如果您不输入到期日期,到期日期将自动设置为比当前日期晚 365 天。
    • 默认情况下,此日期最多可以比当前日期晚 365 天。
  5. 设置选择范围
  6. 选择 创建个人访问令牌

将个人访问令牌保存在安全的地方。离开页面后,您将无法再访问令牌。

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

您可以直接链接到个人访问令牌页面,并在表单中预先填写名称和范围列表。为此,您可以向 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. 有效的个人访问令牌 区域,在密钥旁边,选择 撤销

查看上次使用令牌的时间

令牌使用情况每 24 小时更新一次。每次使用令牌请求 API 资源GraphQL API 时都会更新它。

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

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

个人访问令牌范围

个人访问令牌不再能够访问容器镜像库或软件包库于 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 操作(如果经过身份验证的用户是管理员)。
caution 如果启用了外部授权,个人访问令牌无法访问容器镜像库或软件包库。如果您使用个人访问令牌访问它们,系统会中断对这些令牌的使用。禁用外部授权可以将个人访问令牌用于容器镜像库或软件包库。

个人访问令牌到期时

个人访问令牌在您定义的日期(UTC 午夜)到期。

  • 极狐GitLab 在每天 01:00 AM UTC 运行检查,以识别在接下来的 7 天内到期的个人访问令牌。这些令牌的所有者会收到电子邮件通知。
  • 极狐GitLab 每天在 UTC 时间凌晨 02:00 运行检查,以识别在当前日期过期的个人访问令牌。这些令牌的所有者会收到电子邮件通知。
  • 在旗舰版中,管理员可以限制个人访问令牌的生命周期

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

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

先决条件:

  • 您需要足够的访问权限才能为您的实例运行 Rails 控制台会话

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

  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')
    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'); token.set_token('token-string-here123'); token.save!"

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

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

先决条件:

  • 您需要足够的访问权限才能为您的实例运行 Rails 控制台会话

以编程方式撤销令牌:

  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-cn/gitlab.git

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

git clone https://<username>@jihulab.com/gitlab-cn/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