群组访问令牌

有了群组访问令牌，您可以使用单个令牌来：

  • 执行群组操作。
  • 管理群组内的项目。

您还可以使用群组令牌来进行身份验证：

  • 使用极狐GitLab API。

  • 使用 Git over HTTPS。使用：

    • 使用任何非空值作为用户名。
    • 使用群组令牌作为密码。

在 JihuLab.com 上，如果您使用的是专业版或旗舰版，那么您可以使用群组访问令牌。试用许可证中群组访问令牌不可用。 在私有化部署实例上，您可以在任何许可证级别使用群组访问令牌。如果您使用的是基础版： - 在用户设置中查看您的安全和合规策略。 - 考虑禁用群组访问令牌 以降低潜在滥用。

群组访问令牌和项目访问令牌、个人访问令牌类似，除非它们与一个群组相关联，而不是与一个项目或用户相关联。

在私有化部署实例上，如果设置了限制，则群组访问令牌和个人访问令牌，使用相同的最大生命周期限制。

您无法使用群组访问令牌来创建其他群组、项目或个人访问令牌。

群组访问令牌会继承为个人访问令牌配置的默认前缀设置。

使用 UI 创建群组访问令牌

  • 从 15.3 版本开始，默认到期时间为 30 天，并且在 UI 中填充默认的访客角色。
  • 创建不会过期的群组访问令牌的功能删除于 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. 选择 所需的范围。
  8. 选择 创建群组访问令牌。

显示群组访问令牌。将群组访问令牌保存在安全的地方。离开或刷新页面后，您将无法再次查看。

caution 群组访问令牌被当作内部用户处理。如果内部用户创建群组访问令牌，该令牌将能够访问所有设置为内部可见性的项目。

使用 Rails 控制台创建群组访问令牌

如果您是管理员，您可以在 Rails 控制台上创建群组访问令牌。

  1. 在 Rails 控制台中运行以下命令：

    # Set the GitLab administration user to use. If user ID 1 is not available or is not an administrator, use 'admin = User.admins.first' instead to select an administrator.
admin = User.find(1)

# Set the group group you want to create a token for. For example, group with ID 109.
group = Group.find(109)

# Create the group bot user. For further group access tokens, the username should be group_#{group.id}_bot#{bot_count}. For example, group_109_bot2 and email address group_109_bot2@example.com.
bot = Users::CreateService.new(admin, { name: 'group_token', username: "group_#{group.id}_bot", email: "group_#{group.id}_bot@example.com", user_type: :project_bot }).execute

# Confirm the group bot.
bot.confirm

# Add the bot to the group with the required role.
group.add_member(bot, :maintainer)

# Give the bot a personal access token.
token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token')

# Get the token value.
gtoken = token.token

  2. 测试生成的群组访问令牌是否有效：

    1. 将 PRIVATE-TOKEN header 中的群组访问令牌与 GitLab REST API 一起使用。例如：

    2. 使用群组令牌通过 HTTPS 克隆群组的项目。

撤销群组访问令牌

  • 查看撤销的令牌能力引入于极狐GitLab 17.3，使用名为 retain_resource_access_token_user_after_revoke 的功能标志。默认禁用。

在极狐GitLab 17.3 及以后版本，如果启用了 retain_resource_access_token_user_after_revoke 功能标志，您可以在访问令牌页面查看活动和已撤销的群组访问令牌。如果您没有启用功能标志，您只能查看活动令牌。不活跃的群组访问令牌表：

  • 包含：
    • 既有令牌被撤销但是未过期。过期日之后，令牌将不再显示在表中。
    • 在启用功能标志之后创建的令牌被撤销。即使它们已经过期，这些令牌也会保留在表中。
  • 不包含：
    • 已经过期或被撤销的令牌。
    • 既有令牌即将过期或已被撤销。

使用 UI

要撤销群组访问令牌：

  1. 在左侧导航栏中，选择 搜索或转到，然后找到您的群组。
  2. 选择 设置 > 访问令牌。
  3. 在要撤销的群组访问令牌旁边，选择 撤销 ( )。

群组访问令牌的范围

  • k8s_proxy 引入于极狐GitLab 16.4，使用名为 k8s_proxy_pat 的功能标志。默认启用。
  • k8s_proxy 功能标志在极狐GitLab 16.5 中被移除。

范围确定您在使用群组访问令牌进行身份验证时可以执行的操作。

范围 描述
api 授予对群组和相关项目 API 的完整读写访问权限，包括软件包库。
read_api 授予对群组和相关项目 API 的读访问权限，包括软件包库。
read_registry 如果群组中的任何项目是私有的并且需要授权，则允许对 Container Registry 镜像进行读取访问（拉取）。
write_registry 允许对 Container Registry 的写入访问（推送）。
read_repository 允许对群组内的所有仓库进行读取访问（拉取）。
write_repository 允许对群组内的所有仓库进行读写访问（拉取和推送）。
create_runner 允许在群组中创建 runner 的权限。
manage_runner 允许在群组中管理 runner 的权限。
k8s_proxy 允许在群组中使用 Kubernetes agent 来执行 Kubernetes API 的权限。

启用或禁用群组访问令牌创建

为顶级群组中的所有子组启用或禁用群组访问令牌创建：

  1. 在左侧导航栏，选择 搜索或前往 并找到您的群组。
  2. 选择 设置 > 通用。
  3. 展开 权限和群组功能。
  4. 在 权限 下，打开或关闭 用户可以在该群组中创建项目访问令牌和群组访问令牌。
  5. 选择 保存更改。

即使禁用创建，您仍然可以使用和撤销现有的群组访问令牌。

访问令牌过期

既有群组访问令牌的过期日期是否自动应用取决于您的订阅计划，当您升级到极狐GitLab 16.0 或更高版本时：

  • 在 JihuLab.com 上，在 16.0 里程碑期间，现有的群组访问令牌若没有到期日期，将被自动设置一个到期日期，该日期比当前日期晚 365 天。
  • 在私有化部署实例上，如果从 15.11 或更早版本升级到 16.0 或更高版本，
    • 在或之前 2024 年 7 月 23 日，现有的群组访问令牌若没有到期日期，将被自动设置一个到期日期，该日期比当前日期晚 365 天。
    • 在或之后 2024 年 7 月 23 日，现有的群组访问令牌若没有到期日期，将不会被设置到期日期。

在极狐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 的功能标志。默认禁用。
此功能受控于功能标志。更多详情，可以查看历史。

极狐GitLab 会在每天 1:00 AM UTC 时间运行检查来识别近期将过期的群组访问令牌。直接拥有群组所有权的成员会收到电子邮件通知，当检查识别出群组访问令牌将在接下来的 60 天或 30 天内过期时，会发送额外的电子邮件：

  • 在极狐GitLab 17.6 及以后版本，群组所有权持有人会收到电子邮件通知，当检查识别出群组访问令牌将在接下来的 60 天或 30 天内过期时，会发送额外的电子邮件。
  • 当检查识别出群组访问令牌将在接下来的 7 天内过期时，会发送电子邮件通知。

群组的机器人用户

每次创建组访问令牌时，都会创建一个机器人用户并将其添加到群组中。这些 bot 用户类似于项目机器人用户，不同之处在于它们被添加到群组而不是项目中。群组的机器人用户：

  • 不计入许可证席位。
  • 可以拥有一个群组的最大所有者角色。
  • 将第一个访问令牌的用户名设置为 group_{group_id}_bot。例如，group_123_bot。
  • 将电子邮件设置为 group{group_id}_bot@noreply.{Gitlab.config.gitlab.host}。例如，group123_bot@noreply.example.com。

令牌可用性

群组访问令牌只在付费计划中可用。