GitLab token 概述

本文档列出了 GitLab 中使用的 token、其用途以及（如适用）安全指南。

安全注意事项

为保护您的 token 安全：

• 将 token 视同密码并妥善保管。
• 创建作用域 token 时，使用尽可能最小化的权限范围，以减少意外泄露 token 的影响。
  • 如果不同进程需要不同权限（例如 read 和 write），考虑使用单独的 token，每个权限范围对应一个。如果一个 token 泄露，其权限范围比具有广泛权限（如完整 API 访问）的单个 token 更小。
• 创建 token 时：
  • 选择描述性的名称，例如 GITLAB_API_TOKEN-application1 或 GITLAB_READ_API_TOKEN-application2。避免使用通用名称如 GITLAB_API_TOKEN、API_TOKEN 或 default。
  • 考虑设置任务完成后过期的 token。例如，如需执行一次性导入，可将 token 设置为几小时后过期。
  • 添加描述性说明，提供相关上下文（包括任何相关 URL）。
• 如果设置演示环境展示您开发的项目，并录制视频或撰写博客描述该项目，请确保不会意外泄露密钥。演示结束后，撤销演示期间创建的所有密钥。
• 将 token 添加到 URL 可能存在安全风险。建议通过 Private-Token 等头部传递 token。
  • 克隆或添加包含 token 的远程 URL 时，Git 会将 URL 以明文写入 .git/config 文件。
  • 代理和应用服务器通常会记录 URL，可能导致凭证泄露给系统管理员。
• 可使用 Git 凭证存储 存储 token。
• 定期审查所有类型的活跃访问 token，撤销不再需要的 token。

禁止：

• 在项目中以明文存储 token。如果 token 是 GitLab CI/CD 的外部密钥，请参考 CI/CD 外部密钥使用指南。
• 在粘贴代码、控制台命令或日志输出到 issue、MR 描述、评论或其他自由文本输入时包含 token。
• 在控制台日志或产物中记录凭证。建议 保护 和 屏蔽 您的凭证。

CI/CD 中的 token

尽可能避免使用个人访问 token 作为 CI/CD 变量，因其权限范围过广。如果 CI/CD 作业需要访问其他资源，请按权限范围从小到大使用以下类型：

1. 作业 token（权限范围最小）
2. 项目 token
3. 组 token

CI/CD 变量安全 的其他建议包括：

• 对所有凭证使用 密钥存储。
• 包含敏感信息的 CI/CD 变量应 受保护、被屏蔽 和 隐藏。

个人访问 token

您可以创建 个人访问 token 用于：

• GitLab API 认证。
• GitLab 仓库认证。
• GitLab 注册表认证。

您可以限制个人访问 token 的权限范围和过期时间。默认情况下，它们继承创建用户的权限。

您可以使用个人访问 token API 以编程方式执行操作，例如 轮换个人访问 token。

当个人访问 token 即将过期时，您会 收到邮件通知。

在需要 token 授权的 CI/CD 作业场景中，避免使用个人访问 token（尤其是作为 CI/CD 变量存储时）。CI/CD 作业 token 和项目访问 token 通常能以更低风险实现相同效果。

OAuth 2.0 token

GitLab 可作为 OAuth 2.0 提供者，允许其他服务代表用户访问 GitLab API。

您可以限制 OAuth 2.0 token 的权限范围和有效期。

模拟用户 token

模拟用户 token 是一种特殊的个人访问 token，仅管理员可为特定用户创建。模拟用户 token 可帮助您构建应用程序或脚本，以特定用户身份通过 GitLab API、仓库和注册表进行认证。

您可以限制模拟用户 token 的权限范围并设置过期时间。

项目访问 token

项目访问 token 作用于单个项目。与个人访问 token 类似，可用于：

• GitLab API 认证。
• GitLab 仓库认证。
• GitLab 注册表认证。

您可以限制项目访问 token 的权限范围和过期时间。创建项目访问 token 时，GitLab 会为项目创建一个 机器人用户。项目机器人用户属于服务账号，不计入授权席位。

您可以使用 项目访问 token API 以编程方式执行操作，例如 轮换项目访问 token。

拥有至少维护者角色的项目成员在项目访问 token 即将过期时会 收到邮件通知。

组访问 token

组访问 token 作用于单个组。与个人访问 token 类似，可用于：

• GitLab API 认证。
• GitLab 仓库认证。
• GitLab 注册表认证。

您可以限制组访问 token 的权限范围和过期时间。创建组访问 token 时，GitLab 会为组创建一个 机器人用户。组机器人用户属于服务账号，不计入授权席位。

您可以使用 组访问 token API 以编程方式执行操作，例如 轮换组访问 token。

拥有所有者角色的组成员在组访问 token 即将过期时会 收到邮件通知。

部署 token

部署 token 允许您无需用户名和密码即可克隆、推送和拉取项目的包及容器镜像。部署 token 不能用于 GitLab API。

要管理部署 token，您必须是拥有至少维护者角色的项目成员。

部署密钥

部署密钥 通过将 SSH 公钥导入 GitLab 实例，为您的仓库提供只读或读写访问权限。部署密钥不能用于 GitLab API 或注册表。

您可以使用部署密钥将仓库克隆到持续集成服务器，而无需设置虚假用户账号。

要添加或启用项目的部署密钥，您必须拥有至少维护者角色。

Runner 认证 token

在 GitLab 16.0 及更高版本中，注册 Runner 可使用 Runner 认证 token 替代 Runner 注册 token。Runner 注册 token 已被弃用。

创建 Runner 及其配置后，您会收到一个用于注册 Runner 的 Runner 认证 token。该 token 存储在本地 config.toml 文件中（用于配置 Runner）。

Runner 使用 Runner 认证 token 从作业队列获取作业时向 GitLab 认证。认证成功后，Runner 会收到一个作业 token，用于执行作业。

Runner 认证 token 保留在 Runner 机器上。以下执行器的执行环境仅能访问作业 token，无法访问 Runner 认证 token：

• Docker Machine
• Kubernetes
• VirtualBox
• Parallels
• SSH

恶意访问 Runner 文件系统可能暴露 config.toml 文件和 Runner 认证 token。攻击者可利用 Runner 认证 token 克隆 Runner。

您可以使用 Runners API 轮换或撤销 Runner 认证 token。

Runner 注册 token（已弃用）

Runner 注册 token 用于通过 GitLab 注册 Runner。组或项目所有者或实例管理员可通过 GitLab 用户界面获取。注册 token 仅限用于 Runner 注册，无其他权限范围。

您可以使用 Runner 注册 token 添加在项目或组中执行作业的 Runner。Runner 可访问项目代码，因此分配项目或组权限时需谨慎。

CI/CD 作业 token

CI/CD 作业 token 是仅在作业执行期间有效的短期 token。它赋予 CI/CD 作业访问有限 API 端点的权限。API 认证使用作业 token，并遵循触发作业的用户授权。

作业 token 通过其短期有效性和有限权限范围保障安全。如果多个作业在同一台机器上运行（例如使用 shell 执行器），该 token 可能泄露。您可以使用项目允许列表进一步限制作业 token 的访问权限。在 Docker Machine Runner 上，应配置 MaxBuilds=1 确保 Runner 机器仅运行一次构建并在后销毁。此配置可能影响性能，因为预置需要时间。

GitLab 集群代理 token

当您 注册 Kubernetes 的 GitLab 代理 时，GitLab 会生成一个访问 token 用于集群代理向 GitLab 认证。

要撤销此集群代理 token，可通过以下方式：

• 使用 代理 API 撤销 token。
• 重置 token。

两种方法均需知道 token、代理和项目 ID。要查找此信息，请使用 Rails 控制台：

# 查找 token ID
Clusters::AgentToken.find_by_token('glagent-xxx').id

# 查找代理 ID
Clusters::AgentToken.find_by_token('glagent-xxx').agent.id
=> 1234

# 查找项目 ID
Clusters::AgentToken.find_by_token('glagent-xxx').agent.project_id
=> 12345

您也可直接在 Rails 控制台撤销 token：

# 使用 RevokeService 撤销 token（包含生成审计事件）
Clusters::AgentTokens::RevokeService.new(token: Clusters::AgentToken.find_by_token('glagent-xxx'), current_user: User.find_by_username('admin-user')).execute

# 手动撤销 token（不生成审计事件）
Clusters::AgentToken.find_by_token('glagent-xxx').revoke!

其他 token

Feed token

每个用户都有一个永不过期的长期 feed token。使用此 token 进行以下认证：

• RSS 阅读器，加载个性化 RSS 源。
• 日历应用，加载个性化日历。

此 token 不能用于访问任何其他数据。

您可对所有源使用用户范围的 feed token。但源和日历 URL 是使用仅对单个源有效的不同 token 生成的。

任何拥有您 token 的人均可像您本人一样查看您的源活动（包括机密 issue）。如果认为 token 已泄露，请立即重置 token。

禁用 feed token

先决条件：

• 您必须是管理员。

1. 在左侧边栏底部，选择 管理员。
2. 选择 设置 > 常规。
3. 展开 可见性和访问控制。
4. 在 Feed token 下，勾选 禁用 feed token 复选框，然后选择 保存更改。

收件箱 token

每个用户都有一个永不过期的收件箱 token。该 token 包含在关联到个人项目的电子邮件地址中。您使用此 token 通过邮件创建新 issue。

此 token 不能用于访问任何其他数据。任何拥有您 token 的人均可像您本人一样创建 issue 和合并请求。如果认为 token 已泄露，请立即重置 token。

工作空间 token

每个工作空间都有一个内部自动管理的永不过期 token。它允许通过 HTTP 和 SSH 与工作空间通信。只要工作空间处于 运行 状态，该 token 即存在，并由工作空间自动注入和使用。

启动停止的工作空间会创建新的工作空间 token。重启运行中的工作空间会删除现有 token 并创建新 token。

您无法直接查看或管理此内部 token。此 token 不能用于访问任何其他数据。

要撤销工作空间 token，请停止或终止工作空间。token 将立即删除。

可用权限范围

下表显示每种 token 的默认权限范围。部分 token 在创建时可进一步限制权限。

脚注：

1. 限制为单个项目。
2. 限制为单个组。
3. Runner 注册和认证 token 不提供直接仓库访问权限，但可用于注册和认证新 Runner，这些 Runner 可执行具有仓库访问权限的作业。
4. 仅限特定端点。

Token 前缀

下表显示每种 token 的前缀。