项目访问令牌

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

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

• 通过 GitLab API。
• 通过 Git，使用 HTTP Basic Authentication 时，使用：
  • 任何非空值作为用户名。
  • 项目访问令牌作为密码。

项目访问令牌与 群组访问令牌 和 个人访问令牌 类似，但仅限于关联的项目。 您不能使用项目访问令牌来访问属于其他项目的资源。

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

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

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

创建项目访问令牌

要创建项目访问令牌：

1. 在左侧边栏，选择 搜索或跳转 并找到您的项目。
2. 选择 设置 > 访问令牌。
3. 选择 添加新令牌。
4. 在 令牌名称 中，输入一个名称。任何有权限查看该项目的用户都可以看到令牌名称。
5. 可选。在 令牌描述 中，输入令牌的描述。
6. 在 过期日期 中，输入令牌的过期日期。
   • 令牌在该日期的午夜 UTC 过期。过期日期为 2024-01-01 的令牌将在 2024-01-01 00:00:00 UTC 过期。
   • 如果您不输入过期日期，过期日期将自动设置为当前日期的 30 天后。
   • 默认情况下，此日期最多可以比当前日期晚 365 天。在 GitLab 17.6 或更高版本中，您可以将此限制延长至 400 天。
   • 实例范围的 最大生命周期 设置可以限制 GitLab 自托管实例中的最大允许生命周期。
7. 为令牌选择一个角色。
8. 选择所需的 范围。
9. 选择 创建项目访问令牌。

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

撤销或轮换项目访问令牌

在 GitLab 17.9 及更高版本中，您可以在访问令牌页面上查看活动和非活动项目访问令牌。

非活动项目访问令牌表会显示已撤销和过期的令牌，直到它们被 自动删除。

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

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

项目访问令牌的范围

范围决定了您在使用项目访问令牌进行身份验证时可以执行的操作。

Scope	Description
api	Grants complete read and write access to the scoped project API, including the container registry, the dependency proxy, and the package registry.
read_api	Grants read access to the scoped project API, including the package registry.
read_registry	Grants read access (pull) to the container registry images if a project is private and authorization is required.
write_registry	Grants write access (push) to the container registry. You need both read and write access to push images.
read_repository	Grants read access (pull) to the repository.
write_repository	Grants read and write access (pull and push) to the repository.
create_runner	Grants permission to create runners in the project.
manage_runner	Grants permission to manage runners in the project.
ai_features	Grants permission to perform API actions for GitLab Duo. This scope is designed to work with the GitLab Duo Plugin for JetBrains. For all other extensions, see scope requirements.
k8s_proxy	Grants permission to perform Kubernetes API calls using the agent for Kubernetes in the project.
self_rotate	Grants permission to rotate this token using the personal access token API. Does not allow rotation of other tokens.

限制创建项目访问令牌

为了限制潜在的滥用，您可以限制用户为群组层次结构创建令牌。此设置仅可配置为顶级群组，并适用于每个下游项目和子群组。任何现有的项目访问令牌在其过期日期之前或被手动撤销之前都保持有效。

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

访问令牌过期

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

• 在 GitLab.com 上，在 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 每天在 UTC 1:00 运行检查，以识别即将过期的项目访问令牌。当这些令牌在特定天数内过期时，具有至少 Maintainer 角色的项目成员将通过电子邮件收到通知。天数因 GitLab 版本而异：

• 在 GitLab 17.6 及更高版本中，当检查确定其项目访问令牌将在未来 60 天内过期时，项目维护者和所有者会收到电子邮件通知。当检查确定其项目访问令牌将在未来 30 天内过期时，会发送另一封电子邮件。
• 当检查确定其项目访问令牌将在未来 7 天内过期时，项目维护者和所有者会收到电子邮件通知。
• 在 GitLab 17.7 及更高版本中，由于项目属于某个群组而继承了 Owner 或 Maintainer 角色的项目成员也可以接收通知电子邮件。您可以通过以下更改来启用此功能：
  • 项目任何父群组中的 群组设置。
  • 在 GitLab 自托管上，实例设置。

您的过期访问令牌列在 非活动项目访问令牌表 中，直到它们被 自动删除。

项目的机器人用户

项目的机器人用户是 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 调用与相应的机器人用户关联。

项目的机器人用户：

• 包含在项目的成员列表中，但无法修改。
• 不能添加到任何其他项目中。
• 对于项目，最大角色可以是 Owner。有关更多信息，请参阅 创建项目访问令牌。

当项目访问令牌被 撤销 时：

• 机器人用户根据 非活动令牌保留设置 保留。
• 30 天后，机器人用户将被删除。所有记录都将移动到用户名为 Ghost User 的系统级用户。

另请参阅 群组的机器人用户。

非活动令牌保留

默认情况下，GitLab 在令牌家族中最后一个活动令牌变为非活动状态 30 天后，删除群组和项目访问令牌及其 令牌家族。 这将删除令牌家族中的所有令牌和关联的机器人用户，并将机器人用户的贡献迁移到系统级的 “Ghost User”。

要修改非活动令牌的保留期：

1. 在左侧边栏底部，选择 Admin。
2. 选择 设置 > 常规。
3. 展开 账户和限制。
4. 在 非活动项目和群组访问令牌保留期 文本框中，修改保留期。
   • 如果定义了数字，所有群组和项目访问令牌在非活动状态达到指定天数后将被删除。
   • 如果该字段为空，则永远不会删除非活动令牌。
5. 选择 保存更改。

您还可以使用 应用程序设置 API 来修改 inactive_resource_access_tokens_delete_after_days 属性。

令牌可用性

多个项目访问令牌仅在付费订阅中可用。在 Premium 和 Ultimate 试用订阅中，只包含一个项目访问令牌。有关更多信息，请参阅 GitLab 试用常见问题解答 中的 [“包含内容” 部分]。

相关主题

• 项目访问令牌 API