当前位置：首页 > web >正文

如何创建并使用极狐GitLab 项目访问令牌？

web 2025/5/1 15:11:14

极狐GitLab 是 GitLab 在中国的发行版，关于中文参考文档和资料有：

极狐GitLab 中文文档
极狐GitLab 中文论坛
极狐GitLab 官网

项目访问令牌

在极狐GitLab 16.1中引入添加了默认前缀。

项目访问令牌类似于密码，但你可以限制访问资源，选择有限的角色，并提供到期日期。

注意：对项目的实际访问是由角色和权限和令牌作用域的组合控制的。

使用项目访问令牌进行身份验证：

使用GitLab API。
使用Git时，使用HTTP基本认证：
- 任何非空值作为用户名。
- 将项目访问令牌作为密码。

项目访问令牌类似于组访问令牌和个人访问令牌，但项目访问令牌仅限于一个项目，因此无法用于访问其他项目的资源。

在自管理实例中，如果设置了限制，项目访问令牌与个人访问令牌一样，受相同的最大生命周期限制。

你可以在以下环境中使用项目访问令牌：

在极狐SaaS上：如果你拥有Premium或Ultimate许可证层次，试用许可证中只能使用一个项目访问令牌试用许可证。
在极狐GitLab自管理实例中：适用于任何许可证层次。如果你使用的是 Free 层级，可以考虑限制创建项目访问令牌，以降低潜在的滥用风险。

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

项目访问令牌继承了为个人访问令牌配置的默认前缀设置。

创建项目访问令牌

在极狐GitLab 15.1中引入所有者可以为项目访问令牌选择所有者角色。
在极狐GitLab 15.3中引入UI中预设了30天的默认过期时间和默认的访客角色。
在极狐GitLab 16.0中移除创建无过期日期的项目访问令牌的能力。
在极狐GitLab 17.6中引入最大可允许的生命周期限制扩展到400天，并带有名为 buffered_token_expiration_limit 的功能标志，默认禁用。

WARNING:在极狐GitLab 15.4中，创建没有过期日期的项目访问令牌的能力已被弃用，并且在极狐GitLab 16.0中已被移除。有关已添加过期日期的现有令牌的更多信息，请参见访问令牌过期。

要创建项目访问令牌：

1.在左侧边栏中，选择 搜索或转到 并找到你的项目。
2.选择 设置 > 访问令牌。
3.选择 添加新令牌。
4.在 令牌名称 中，输入一个名称。令牌名称对所有具有查看项目权限的用户可见。
5.可选。在 令牌描述 中，输入令牌的描述。
6.在 过期日期 中，输入令牌的过期日期。

令牌将在该日期的 UTC 时间午夜过期。比如，2024-01-01的过期日期将在2024-01-01 00:00:00UTC 过期。
如果没有输入过期日期，过期日期会自动设置为当前日期的30天后。
默认情况下，日期的最大值可以是当前日期的365天后。在极狐GitLab 17.6或更高版本中，你可以扩展此限制至400天。
实例范围的最大生命周期设置可以限制自托管实例中允许的最大生命周期。

7.为令牌选择一个角色。
8.选择所需的作用域。
9.选择 创建项目访问令牌。

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

WARNING:项目访问令牌被视为内部用户。如果内部用户创建了项目访问令牌，则该令牌能够访问所有设置为内部可见性级别的项目。

撤销或轮换项目访问令牌

在极狐GitLab 17.3中引入查看已撤销令牌的功能，带有一个标志名为retain_resource_access_token_user_after_revoke，默认禁用。

在极狐GitLab 17.3及更高版本中，如果启用retain_resource_access_token_user_after_revoke 功能标志，你可以在访问令牌页面上查看活动和非活动的已撤销项目访问令牌。如果未启用该功能标志，你只能查看活动令牌。非活动项目访问令牌表格：

包含：
- 已撤销但尚未过期的现有令牌。此类令牌在过期后将不再显示在表格中。
- 在启用功能标志后创建的并且已被撤销的令牌。这些令牌即使过期后仍将显示在表格中。
不包含：
- 已经过期或已被撤销的令牌。
- 将来会过期或尚未被撤销的现有令牌。

使用UI

要撤销或轮换项目访问令牌：

1.在左侧边栏中，选择 搜索或转到 并找到你的项目。
2.选择 设置 > 访问令牌。
3.对于相关令牌，选择 撤销 ({remove}) 或 轮换 ({retry})。
4,在确认对话框中，选择撤销或轮换。

项目访问令牌的作用域

在极狐GitLab 16.4中引入k8s_proxy，带有一个标志名为k8s_proxy_pat，默认启用。
在极狐GitLab 16.5中移除k8s_proxy_pat功能标志。

作用域决定了当你使用项目访问令牌进行身份验证时可以执行的操作。

NOTE:请参见创建项目访问令牌中关于内部项目的警告。

作用域	描述
`api`	授予对作用域项目API的完全读写访问权限，包括容器注册表、依赖代理和包注册表。
`read_api`	授予对作用域项目API的读取访问权限，包括包注册表。
`read_registry`	授予对容器注册表镜像的读取访问权限（拉取），如果项目是私有的并且需要授权。
`write_registry`	授予对容器注册表的写入访问权限（推送）。推送镜像需要同时拥有读取和写入权限。
`read_repository`	授予对仓库的读取访问权限（拉取）。
`write_repository`	授予对仓库的读写访问权限（拉取和推送）。
`create_runner`	授予在项目中创建运行器的权限。
`manage_runner`	授予管理项目中运行器的权限。
`ai_features`	授予对GitLab Duo执行API操作的权限。此作用域设计为与JetBrains的 GitLab Duo 插件一起使用。对于所有其他扩展，请参阅作用域要求。
`k8s_proxy`	授予使用Kubernetes代理在项目中执行Kubernetes API调用的权限。

限制创建项目访问令牌

为减少滥用风险，你可以限制用户在组层次结构中创建令牌。此设置仅对顶级组可配置，并适用于每个下游项目和子组。任何现有的项目访问令牌在其过期日期或手动撤销之前仍然有效。

1.在左侧边栏中，选择 搜索或转到 并找到你的组。
2.该组必须是顶级组。
3.选择 设置 > 常规。
4.展开 权限和组功能。
5.在权限部分，清除用户可以在该组中创建项目访问令牌和组访问令牌 复选框。

访问令牌过期

是否自动为现有的项目访问令牌应用过期日期，取决于你所使用的极狐GitLab 版本以及你何时升级到极狐GitLab 16.0或更高版本：

在极狐saas上，在16.0版本时，现有没有过期日期的项目访问令牌会自动添加一个过期日期，通常为当前日期后的365天。
在极狐GitLab自管理版中，如果你从极狐GitLab 15.11或更早版本升级到极狐GitLab 16.0或更高版本：
- 在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

项目访问令牌过期通知邮件

在极狐GitLab 17.6中引入六十天和三十天过期通知邮件，带有一个标志名为 expiring_pats_30d_60d_notifications，默认禁用。

极狐GitLab每天1:00 AM UTC进行一次检查，以识别即将过期的项目访问令牌。当检查识别出项目访问令牌将在接下来的特定天数内过期时，至少拥有维护者角色的项目成员会通过邮件通知他们的令牌过期。不同版本的极狐GitLab有不同的通知规则：

在极狐GitLab 17.6及更高版本中，项目的维护者和所有者将在令牌将在接下来的60天内过期时通过邮件通知。检查发现令牌将在接下来的30天内过期时，还会发送另一封邮件通知。
项目的维护者和所有者将在令牌将在接下来的7天内过期时通过邮件通知。

项目机器人的用户

在极狐GitLab 17.2中更改带有一个标志名为 retain_resource_access_token_user_after_revoke，默认禁用。启用后，新的机器人用户没有。

项目机器人的用户是GitLab 创建的非计费用户。
每次创建项目访问令牌时，都会创建一个机器人用户并将其添加到项目中。

该用户不是计费用户，因此不计入许可证限制。

项目机器人的用户具有与项目访问令牌所选角色和作用域相对应的权限。

名称设置为令牌的名称。
用户名设置为project_{project_id}_bot_{random_string}，例如project_123_bot_4ffca233d8298ea1。
电子邮件设置为project_{project_id}_bot_{random_string}@noreply.{Gitlab.config.gitlab.host}，例如project_123_bot_4ffca233d8298ea1@noreply.example.com。

使用项目访问令牌进行的API调用将与相应的机器人用户关联。
项目机器人的用户：