项目访问令牌

版本历史

• 在极狐GitLab 16.1 中为试用订阅引入。

项目访问令牌提供对特定项目的认证访问。它们类似于群组访问令牌和个人访问令牌，但作用域限定于关联的项目，而不是群组或用户。你不能使用项目访问令牌访问其他项目中的资源，也不能创建其他群组、项目或个人访问令牌。

你可以使用项目访问令牌进行认证：

• 通过 极狐GitLab API。
• 通过 HTTPS 使用 Git。使用：
  • 任何非空值作为用户名。
  • 项目访问令牌作为密码。

前提条件：

• 在项目中具有维护者或所有者角色。

查看你的访问令牌#

版本历史

• 在极狐GitLab 16.0 及更早版本中，令牌使用信息每 24 小时更新一次。
• 令牌使用信息更新频率已更改，在极狐GitLab 16.1 中从 24 小时更改为 10 分钟。
• 查看 IP 地址的功能引入于极狐GitLab 17.8，带有功能标志 pat_ip。在 17.9 中默认启用。
• 查看 IP 地址的功能已全面可用于极狐GitLab 17.10。功能标志 pat_ip 已移除。

项目访问令牌页面显示有关你的访问令牌的信息。

在此页面上，你可以执行以下操作：

• 创建、轮换和撤销项目访问令牌。
• 查看所有活跃和非活跃的项目访问令牌。
• 查看令牌信息，包括作用域、分配的角色和到期日期。
• 查看使用信息，包括使用日期以及最近五个不同的连接 IP 地址。
  当令牌执行 Git 操作或通过REST 或 GraphQL API 认证操作时，极狐GitLab 会定期更新令牌使用信息。令牌使用时间每 10 分钟更新一次，令牌使用 IP 地址每分钟更新一次。

要查看你的项目访问令牌：

1. 在顶部栏中，选择 搜索或跳转到 并找到你的项目。
2. 在左侧边栏中，选择 设置 > 访问令牌。

活跃且可用的令牌存储在 活跃的项目访问令牌 部分。已过期、已轮换或已撤销的令牌存储在 非活跃的项目访问令牌 部分。

创建项目访问令牌#

版本历史

• 创建永不过期的项目访问令牌的功能在极狐GitLab 16.0 中已移除。
• 最大允许生命周期限制在极狐GitLab 17.6 中已延长至 400 天，带有功能标志 buffered_token_expiration_limit。默认禁用。
• 项目访问令牌描述引入于极狐GitLab 17.7。

要创建项目访问令牌：

1. 在顶部栏中，选择 搜索或跳转到 并找到你的项目。
2. 在左侧边栏中，选择 设置 > 访问令牌。
3. 选择 添加新令牌。
4. 在 令牌名称 中，输入一个名称。令牌名称对任何有权查看项目的用户可见。
5. 可选。在 令牌描述 中，输入令牌的描述。
6. 在 到期日期 中，输入令牌的到期日期。
   • 令牌在该日期的 UTC 午夜到期。
   • 如果你不输入日期，到期日期将设置为从今天起 365 天。
   • 默认情况下，到期日期不能超过从今天起 365 天。在极狐GitLab 17.6 及更高版本中，管理员可以修改访问令牌的最大生命周期。
7. 为令牌选择一个角色。
8. 选择一个或多个项目访问令牌作用域。
9. 选择 创建项目访问令牌。

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

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

项目访问令牌作用域#

版本历史

• k8s_proxy 引入于极狐GitLab 16.4，带有功能标志 k8s_proxy_pat。默认启用。
• 功能标志 k8s_proxy_pat 在极狐GitLab 16.5 中已移除。
• self_rotate 引入于极狐GitLab 17.9。默认启用。

作用域定义了使用项目访问令牌进行认证时可用的操作。

轮换项目访问令牌#

版本历史

• 查看已过期和已撤销令牌的功能引入于极狐GitLab 17.3，带有功能标志 retain_resource_access_token_user_after_revoke。默认禁用。
• 查看已过期和已撤销令牌直到其被自动删除的功能在极狐GitLab 17.9 中已全面可用。功能标志 retain_resource_access_token_user_after_revoke 已移除。

轮换令牌会创建一个具有与原令牌相同权限和作用域的新令牌。 原令牌立即变为非活跃状态，极狐GitLab 会保留这两个版本以供审计。你可以在访问令牌页面上查看活跃和非活跃的令牌。

在私有化部署实例上，你可以修改非活跃令牌的保留期。

要轮换项目访问令牌：

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

撤销项目访问令牌#

版本历史

• 查看已过期和已撤销令牌的功能引入于极狐GitLab 17.3，带有功能标志 retain_resource_access_token_user_after_revoke。默认禁用。
• 查看已过期和已撤销令牌直到其被自动删除的功能在极狐GitLab 17.9 中已全面可用。功能标志 retain_resource_access_token_user_after_revoke 已移除。

撤销令牌会立即使其失效并阻止进一步使用。已撤销的令牌不会被立即删除，但你可以过滤令牌列表以仅显示活跃令牌。默认情况下，极狐GitLab 会在 30 天后删除已撤销的群组和项目访问令牌。更多信息，请参见非活跃令牌保留。

要撤销项目访问令牌：

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

访问令牌过期#

个人、群组和项目访问令牌在到期日期的 UTC 午夜到期。过期后，它们不能再用于认证请求。

在极狐GitLab 16.0 及更高版本中，新访问令牌必须有一个到期日期。如果在创建令牌时未明确设置到期日期，则会应用从当前日期起 365 天的到期日期。在极狐GitLab 旗舰版中，管理员可以为访问令牌配置最大允许生命周期。

根据你的极狐GitLab 版本和提供方式，在升级极狐GitLab 版本时，你现有的访问令牌可能会自动应用到期日期。更多信息，请参见非过期访问令牌。

项目访问令牌到期电子邮件#

版本历史

• 60 天和 30 天到期通知引入于极狐GitLab 17.6，带有功能标志 expiring_pats_30d_60d_notifications。默认禁用。
• 60 天和 30 天通知在极狐GitLab 17.7 中已全面可用。功能标志 expiring_pats_30d_60d_notifications 已移除。
• 向继承的群组成员发送通知引入于极狐GitLab 17.7，带有功能标志 pat_expiry_inherited_members_notification。默认禁用。
• 功能标志 pat_expiry_inherited_members_notification 在极狐GitLab 17.10 中默认启用。
• 功能标志 pat_expiry_inherited_members_notification 在极狐GitLab 17.11 中已移除。

极狐GitLab 每天凌晨 1:00 UTC 运行一次检查，以识别即将到期的项目访问令牌。 具有所有者或维护者角色的直接成员会在令牌到期前七天收到电子邮件通知。在极狐GitLab 17.6 及更高版本中，还会在令牌到期前 30 天和 60 天发送通知。

在极狐GitLab 17.7 及更高版本中，具有继承的所有者或维护者角色的成员也可以收到这些电子邮件。你可以在极狐GitLab 实例或特定的父群组上为每个群组和项目配置此功能。如果应用于父群组，此设置将被所有后代群组和项目继承。

已过期的令牌会显示在非活跃的项目访问令牌部分，直到它们被自动删除。在私有化部署实例上，你可以修改此保留期。

项目的机器人用户#

版本历史

• 已更改于极狐GitLab 17.2，带有功能标志 retain_resource_access_token_user_after_revoke。默认禁用。启用后，新的机器人用户将被创建为无到期日期的成员，并且当令牌稍后被撤销或过期时，机器人用户会保留 30 天。
• 非活跃机器人用户保留在极狐GitLab 17.9 中已全面可用。功能标志 retain_resource_access_token_user_after_revoke 已移除。

当你创建项目访问令牌时，极狐GitLab 会创建一个机器人用户并将其与该令牌关联。

机器人用户具有以下属性：

• 它们被授予与关联访问令牌的角色和作用域相对应的权限。
• 它们是项目的成员，但不能从项目中移除，也不能直接添加到任何其他群组或项目。
• 它们是不计费用户，不计入你的许可限制。
• 它们的贡献与机器人用户账户关联。
• 当被移除时，它们的贡献会转移给一个幽灵用户。

创建机器人用户时，会定义以下属性：

限制项目访问令牌的创建#

为了限制潜在的滥用，你可以限制用户在顶级群组中为项目创建访问令牌。任何现有的令牌将保持有效，直到它们过期或被手动撤销。

更多信息，请参见限制群组和项目访问令牌的创建。

相关主题#

• 个人访问令牌
• 群组访问令牌
• 项目访问令牌 API