极狐GitLab CI/CD 作业令牌

当一个 CI/CD 流水线任务即将运行时，极狐GitLab 会生成一个唯一的令牌，并将其作为 CI_JOB_TOKEN 预定义变量 提供给任务。该令牌仅在任务运行时有效。任务完成后，令牌访问将被撤销，您无法再使用该令牌。

使用 CI/CD 任务令牌从正在运行的任务中验证某些极狐GitLab 功能。令牌获得与触发流水线的用户相同的访问级别，但比个人访问令牌具有更少的资源访问权限。用户可以通过执行诸如提交推送、触发手动任务或成为计划流水线的所有者来导致任务运行。此用户必须具有拥有所需权限的角色，以便访问资源。

您可以使用任务令牌验证极狐GitLab，以访问其他群组或项目的资源（目标项目）。默认情况下，任务令牌的群组或项目必须添加到目标项目的允许列表。

如果项目是公共或内部的，您可以在不在允许列表中的情况下访问某些功能。例如，您可以从项目的公共流水线中获取产物。此访问也可以受到限制。

任务令牌访问#

CI/CD 任务令牌可以访问以下资源：

极狐GitLab CI/CD 任务令牌安全性#

如果任务令牌泄漏，它可能会被用于访问触发 CI/CD 任务的用户可访问的私人数据。为了帮助防止令牌泄漏或滥用，极狐GitLab：

• 在任务日志中掩盖任务令牌。
• 仅在任务运行时授予任务令牌权限。

您还应该配置您的 runners 以确保安全：

• 如果机器被重复使用，避免使用 Docker privileged 模式。
• 当任务在同一台机器上运行时，避免使用 shell 执行器。

不安全的极狐GitLab Runner 配置增加了有人从其他任务中窃取令牌的风险。

控制任务令牌对您项目的访问#

您可以控制哪些群组或项目可以使用任务令牌进行验证并访问您项目的某些资源。

默认情况下，任务令牌访问仅限于您项目中流水线中运行的 CI/CD 任务。要允许其他群组或项目使用来自其他项目流水线的任务令牌进行验证：

• 您必须将群组或项目添加到任务令牌允许列表。
• 触发任务的用户必须是您项目的成员。
• 用户必须拥有执行操作的权限。

如果您的项目是公共或内部项目，某些公开可访问的资源可以使用来自任何项目的任务令牌进行访问。这些资源也可以仅限于允许列表中的项目。

极狐GitLab私有化部署管理员可以覆盖并强制执行此设置。当设置被强制执行时，CI/CD 任务令牌始终限制在项目的允许列表中。

将群组或项目添加到任务令牌允许列表#

您可以将群组或项目添加到您的任务令牌允许列表，以允许使用任务令牌进行身份验证访问您的项目资源。默认情况下，任何项目的允许列表仅包括其自身。只有在需要跨项目访问时才添加群组或项目到允许列表。

将项目添加到允许列表不会给允许项目的成员额外的权限。他们必须已经拥有访问您项目资源的权限，才能使用来自允许项目的任务令牌访问您的项目。

例如，项目 A 可以将项目 B 添加到项目 A 的允许列表。项目 B （"被允许的项目"）中的 CI/CD 任务现在可以使用 CI/CD 任务令牌进行身份验证以访问项目 A 的 API 调用。

前提条件：

• 您必须至少拥有当前项目的维护者角色。如果允许项目是内部或私人项目，您必须至少在该项目中拥有访客角色。
• 您不能在允许列表中添加超过 200 个群组和项目。

要将群组或项目添加到允许列表：

1. 在左侧边栏，选择 搜索或转到 并找到您的项目。
2. 选择 设置 > CI/CD。
3. 展开 任务令牌权限。
4. 确保启用了 授权群组和项目 切换。默认情况下在新项目中启用。 禁用此功能是安全风险，因此项目维护者或所有者应始终保持此设置启用。
5. 选择 添加群组或项目。
6. 输入要添加到允许列表的群组或项目的路径，然后选择 添加。

您还可以使用API将群组或项目添加到允许列表。

自动填充项目的允许列表#

您可以使用任务令牌身份验证日志中的数据通过 UI 或 Rake 任务自动填充项目的允许列表。

无论哪种情况，极狐GitLab 都会使用身份验证日志来确定要添加到允许列表的项目或群组，并为您添加这些条目。

此过程最多在项目的允许列表中创建 200 个条目。如果身份验证日志中存在超过 200 个条目，它将压缩允许列表，以保持在 200 个条目限制之下。

使用 UI#

要通过 UI 自动填充允许列表：

1. 在左侧边栏，选择 搜索或转到 并找到您的项目。
2. 选择 设置 > CI/CD。
3. 展开 任务令牌权限。
4. 选择 添加 并从下拉列表中选择 身份验证日志中的所有项目。
5. 对话框要求您确认操作，选择 添加条目。

过程完成后，允许列表包含身份验证日志中的条目。 如果尚未设置，则 授权群组和项目 设置为 仅此项目和允许列表中的群组和项目。

使用 Rake 任务#

具有rails 控制台访问权限的极狐GitLab 管理员可以运行 Rake 任务来自动填充实例上的所有或部分项目的允许列表。此任务还将 授权群组和项目 设置为 仅此项目和允许列表中的群组和项目。

ci:job_tokens:allowlist:autopopulate_and_enforce Rake 任务具有以下配置选项：

• PREVIEW：执行干运行并输出将采取的步骤，但不更改任何数据。
• ONLY_PROJECT_IDS：仅对提供的项目 ID（最多 1000 个 ID）进行迁移。
• EXCLUDE_PROJECT_IDS：对实例上的所有项目进行迁移，除了提供的项目 ID（最多 1000 个 ID）。

ONLY_PROJECT_IDS 和 EXCLUDE_PROJECT_IDS 不能同时使用。

例如：

• ci:job_tokens:allowlist:autopopulate_and_enforce PREVIEW=true
• ci:job_tokens:allowlist:autopopulate_and_enforce PREVIEW=true ONLY_PROJECT_IDS=2,3
• ci:job_tokens:allowlist:autopopulate_and_enforce PREVIEW=true EXCLUDE_PROJECT_IDS=2,3
• ci:job_tokens:allowlist:autopopulate_and_enforce
• ci:job_tokens:allowlist:autopopulate_and_enforce ONLY_PROJECT_IDS=2,3
• ci:job_tokens:allowlist:autopopulate_and_enforce EXCLUDE_PROJECT_IDS=2,3

要运行 Rake 任务：

shell
sudo gitlab-rake ci:job_tokens:allowlist:autopopulate_and_enforce

shell
sudo -u git -H bundle exec rake ci:job_tokens:allowlist:autopopulate_and_enforce

允许列表压缩#

允许列表压缩算法：

1. 扫描授权日志以识别项目的最近公共群组。
2. 将多个项目级条目合并为单个群组级条目。
3. 更新允许列表以包含这些合并的条目。

例如，允许列表如下所示：

plaintext
group1/group2/group3/project1
group1/group2/group3/project2
group1/group2/group4/project3
group1/group2/group4/project4
group1/group5/group6/project5

压缩算法：

1. 将列表压缩为：

   plaintext
   group1/group2/group3
   group1/group2/group4
   group1/group2/group6

2. 如果允许列表超过 200 个条目限制，算法再次压缩：

   plaintext
   group1/group2
   group1/group5

3. 如果允许列表仍然超过 200 个条目限制，算法继续：

   plaintext
   group1

此过程持续进行，直到允许列表条目数为 200 个或更少。

限制公共或内部项目的任务令牌范围#

不在允许列表中的项目可以使用任务令牌验证公共或内部项目以：

• 获取产物。
• 访问容器注册表。
• 访问软件包注册表。
• 访问发布、部署和环境。

您可以通过设置每个功能仅对项目成员可见来限制这些操作的访问仅限于允许列表中的项目。

前提条件：

• 您必须拥有项目的维护者角色。

要将功能设置为仅对项目成员可见：

1. 在左侧边栏，选择 搜索或转到 并找到您的项目。
2. 选择 设置 > 常规。
3. 展开 可见性、项目功能、权限。
4. 将要限制访问的功能的可见性设置为 仅项目成员。
   • 获取产物的能力由 CI/CD 可见性设置控制。
5. 选择 保存更改。

允许任何项目访问您的项目#

如果您禁用 限制访问 到 此项目 设置，则允许列表将被忽略。任何项目的任务都可以使用任务令牌访问您的项目，如果触发流水线的用户有权访问您的项目。

您应该仅在测试或类似原因时禁用此设置，并应尽快重新启用它。

前提条件：

• 您必须至少拥有项目的维护者角色。

要禁用任务令牌范围允许列表：

1. 在左侧边栏，选择 搜索或转到 并找到您的项目。
2. 选择 设置 > CI/CD。
3. 展开 任务令牌权限。
4. 将 授权群组和项目 切换为禁用。 默认情况下在新项目中启用。

您还可以使用 GraphQL (inboundJobTokenScopeEnabled) 和 REST API 启用和禁用设置。

允许 Git 推送请求到您的项目仓库#

您可以允许 Git 推送请求到您的项目仓库，这些请求是通过 CI/CD 任务令牌验证的。当启用时，仅允许在您项目的流水线中运行的 CI/CD 任务生成的令牌访问。默认情况下禁用此权限。

前提条件：

• 您必须至少拥有项目的维护者角色。

要授予生成的任务令牌推送到项目仓库的权限：

1. 在左侧边栏，选择 搜索或转到 并找到您的项目。
2. 选择 设置 > CI/CD。
3. 展开 任务令牌权限。
4. 在 权限 部分，选择 允许 Git 推送请求到仓库。

任务令牌具有与启动任务的用户相同的访问权限。 来自其他允许列表中的项目或群组的任务令牌无法推送到您项目的仓库。

您还可以使用 projects REST API 端点中的 ci_push_repository_for_job_token_allowed 参数来控制此设置。

任务令牌的细粒度权限#

任务令牌的细粒度权限是一个实验。有关此功能和可用资源的信息，请参阅CI/CD 任务令牌的细粒度权限。

使用任务令牌#

使用 git clone 克隆私人项目的仓库#

您可以使用任务令牌验证并在 CI/CD 任务中克隆私人项目的仓库。使用 gitlab-ci-token 作为用户，并将任务令牌的值作为密码。例如：

shell
git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.example.com/<namespace>/<project>

即使通过群组、项目或实例设置禁用 HTTPS 协议，您也可以使用此任务令牌克隆仓库。

验证 REST API 请求#

您可以使用任务令牌验证允许的 REST API 端点请求。例如：

shell
curl --verbose --request POST --form "token=$CI_JOB_TOKEN" --form ref=master "https://gitlab.com/api/v4/projects/1234/trigger/pipeline"

此外，还有多种有效的方法可以在请求中传递任务令牌：

• --form "token=$CI_JOB_TOKEN"
• --header "JOB-TOKEN: $CI_JOB_TOKEN"
• --data "job_token=$CI_JOB_TOKEN"

限制您项目的任务令牌访问（已弃用）#

通过创建项目的任务令牌可以访问的项目的允许列表来控制项目的任务令牌范围。

默认情况下，允许列表包括您当前的项目。 其他项目可以由具有访问权限的维护者添加和删除。

禁用设置时，所有项目都被视为在允许列表中，任务令牌仅受用户的访问权限限制。

例如，当启用设置时，项目 A 中流水线中的任务具有 CI_JOB_TOKEN 范围，仅限于项目 A。如果任务需要使用令牌对项目 B 进行 API 请求，那么 B 必须被添加到 A 的允许列表中。

配置任务令牌范围（已弃用）#

前提条件：

• 您不能在令牌的范围中添加超过 200 个项目。

要配置任务令牌范围：

1. 在左侧边栏，选择 搜索或转到 并找到您的项目。
2. 选择 设置 > CI/CD。
3. 展开 任务令牌权限。
4. 将 限制访问 从 此项目 切换为启用。
5. 可选。将现有项目添加到令牌的访问范围。添加项目的用户必须在两个项目中拥有维护者角色。

任务令牌身份验证日志#

您可以在身份验证日志中跟踪哪些其他项目使用 CI/CD 任务令牌与您的项目进行身份验证。要查看日志：

1. 在左侧边栏，选择 搜索或转到 并找到您的项目。
2. 选择 设置 > CI/CD。
3. 展开 任务令牌权限。身份验证日志部分显示使用任务令牌身份验证访问您项目的其他项目列表。
4. 可选。选择 下载 CSV 以下载完整的身份验证日志 CSV 格式。

身份验证日志最多显示 100 个身份验证事件。如果事件数量超过 100，请下载 CSV 文件以查看日志。

新身份验证到项目可能需要最多 5 分钟才能显示在身份验证日志中。

使用 CI/CD 令牌的旧格式#

从极狐GitLab 18.0 开始，CI/CD 任务令牌默认使用 JWT 标准。从 2025 年 2 月 21 日起在 JihuLab.com 上创建的所有新项目或从极狐GitLab私有化部署 17.10 中创建的项目使用此标准。现有项目可以通过为其项目配置顶级群组继续使用旧格式。此设置仅在极狐GitLab 19.0 版本之前可用。

要为您的 CI/CD 令牌使用旧格式：

1. 在左侧边栏，选择 搜索或转到 并找到您的群组。
2. 选择 设置 > CI/CD。
3. 展开 常规流水线。
4. 关闭 启用 JWT 格式的 CI/CD 任务令牌。

您的 CI/CD 令牌现在使用旧格式。如果您以后想再次使用 JWT 格式，可以重新启用此设置。

故障排除#

CI 任务令牌失败通常显示为类似 404 Not Found 的响应：

• 未授权的 Git 克隆：

  plaintext
  $ git clone https://gitlab-ci-token:$CI_JOB_TOKEN@gitlab.com/fabiopitino/test2.git
  
  Cloning into 'test2'...
  remote: The project you were looking for could not be found or you don't have permission to view it.
  fatal: repository 'https://gitlab-ci-token:[MASKED]@gitlab.com/<namespace>/<project>.git/' not found

• 未授权的软件包下载：

  plaintext
  1$ wget --header="JOB-TOKEN: $CI_JOB_TOKEN" ${CI_API_V4_URL}/projects/1234/packages/generic/my_package/0.0.1/file.txt
  2
  3--2021-09-23 11:00:13--  https://gitlab.com/api/v4/projects/1234/packages/generic/my_package/0.0.1/file.txt
  4Resolving gitlab.com (gitlab.com)... 172.65.251.78, 2606:4700:90:0:f22e:fbec:5bed:a9b9
  5Connecting to gitlab.com (gitlab.com)|172.65.251.78|:443... connected.
  6HTTP request sent, awaiting response... 404 Not Found
  72021-09-23 11:00:13 ERROR 404: Not Found.

• 未授权的 API 请求：

  plaintext
  1$ curl --verbose --request POST --form "token=$CI_JOB_TOKEN" --form ref=master "https://gitlab.com/api/v4/projects/1234/trigger/pipeline"
  2
  3< HTTP/2 404
  4< date: Thu, 23 Sep 2021 11:00:12 GMT
  5{"message":"404 Not Found"}
  6< content-type: application/json

在故障排除 CI/CD 任务令牌身份验证问题时，请注意：

• 提供了一个GraphQL 示例变更，以每个项目切换范围设置。
• 如果任务不再运行、已被删除，或者项目正在删除过程中，CI 任务令牌将失效。

JWT 格式任务令牌错误#

JWT 格式 CI/CD 任务令牌存在一些已知问题。

使用 EC2 Fargate Runner 自定义执行器的 Error when persisting the task ARN. 错误#

在 EC2 Fargate 自定义执行器的 0.5.0 及更早版本中存在一个错误，此问题导致此错误：

• Error when persisting the task ARN. Will stop the task for cleanup

要解决此问题，请升级到 Fargate 自定义执行器的 0.5.1 或更高版本。

invalid character '\n' in string literal 错误与 base64 编码#

如果您使用 base64 编码任务令牌，可能会收到 invalid character '\n' 错误。

base64 命令的默认行为是包装长于 79 个字符的字符串。在任务执行期间 base64 编码 JWT 格式的任务令牌时，例如使用 echo $CI_JOB_TOKEN | base64，令牌被呈现为无效。

要解决此问题，请使用 base64 -w0 禁用自动包装令牌。