配置 runners | 极狐GitLab

设置最大作业超时时间
最大作业超时时间如何工作
设置 script 和 after_script 超时时间
- 确保 after_script 执行
保护敏感信息
配置长轮询
在派生项目中使用实例 runner
重置项目的 runner 注册令牌（已弃用）
身份验证令牌安全性
- 重置 runner 配置身份验证令牌
- 自动轮换 runner 身份验证令牌
防止 runner 泄露敏感信息
控制 runner 可以运行的作业
使用变量配置 runner 行为

Tier: 基础版，专业版，旗舰版
Offering: JihuLab.com，私有化部署

本文档描述了如何在极狐GitLab 用户界面中配置 runner。

如果需要在安装极狐GitLab Runner 的机器上配置 runner，请参阅极狐GitLab Runner 文档。

设置最大作业超时时间

您可以为每个 runner 指定一个最大作业超时时间，以防止具有较长作业超时时间的项目使用 runner。如果最大作业超时时间比项目中定义的作业超时时间短，则使用最大作业超时时间。

要设置 runner 的最大超时时间，请在 REST API 端点中设置 maximum_timeout 参数 PUT /runners/:id。

对于实例 runner

先决条件：

您必须是管理员。

您可以在极狐GitLab 私有化部署中覆盖实例 runner 的作业超时时间。

在 JihuLab.com 上，您无法覆盖极狐GitLab 托管的实例 runner 的作业超时时间，必须使用项目定义的超时时间。

要设置最大作业超时时间：

在左侧边栏底部，选择 管理员。
选择 CI/CD > Runner。
在要编辑的 runner 右侧，选择编辑 ({{< icon name=”pencil” >}})。
在 最大作业超时时间 字段中输入一个秒数。最小值为 600 秒（10 分钟）。
选择 保存更改。

对于群组 runner

先决条件：

您必须具有群组的所有者角色。

要设置最大作业超时时间：

在左侧边栏，选择 搜索或转到 并找到您的群组。
选择 构建 > Runner。
在要编辑的 runner 右侧，选择编辑 ({{< icon name=”pencil” >}})。
在 最大作业超时时间 字段中输入一个秒数。最小值为 600 秒（10 分钟）。
选择 保存更改。

对于项目 runner

先决条件：

您必须具有项目的所有者角色。

要设置最大作业超时时间：

在左侧边栏，选择 搜索或转到 并找到您的项目。
选择 设置 > CI/CD。
展开 Runner。
在要编辑的 runner 右侧，选择编辑 ({{< icon name=”pencil” >}})。
在 最大作业超时时间 字段中输入一个秒数。最小值为 600 秒（10 分钟）。如果未定义，则使用项目的作业超时时间。
选择 保存更改。

最大作业超时时间如何工作

示例 1 - runner 超时时间大于项目超时时间

您将 runner 的 最大作业超时时间 设置为 24 小时。
您将项目的 CI/CD 超时时间 设置为 2 小时。
您开始一个作业。
作业如果运行时间较长，则在 2 小时 后超时。

示例 2 - runner 超时时间未配置

您从 runner 中删除 最大作业超时时间 配置。
您将项目的 CI/CD 超时时间 设置为 2 小时。
您开始一个作业。
作业如果运行时间较长，则在 2 小时 后超时。

示例 3 - runner 超时时间小于项目超时时间

您将 runner 的 最大作业超时时间 设置为 30 分钟。
您将项目的 CI/CD 超时时间 设置为 2 小时。
您开始一个作业。
作业如果运行时间较长，则在 30 分钟 后超时。

设置 `script` 和 `after_script` 超时时间

在极狐GitLab Runner 16.4 中引入。

要控制 script 和 after_script 运行的时间，请在 .gitlab-ci.yml 文件中指定一个超时值。

例如，您可以指定一个超时，以便提前终止长时间运行的 script。这确保在作业超时超过之前，产物和缓存仍然可以上传。 script 和 after_script 的超时时间必须小于作业超时时间。

要为 script 设置超时，请使用作业变量 RUNNER_SCRIPT_TIMEOUT。
要为 after_script 设置超时，并覆盖默认的 5 分钟，请使用作业变量 RUNNER_AFTER_SCRIPT_TIMEOUT。

这两个变量均接受 Go 的持续时间格式（例如，40s、1h20m、2h、4h30m30s）。

例如：

job-with-script-timeouts:
  variables:
    RUNNER_SCRIPT_TIMEOUT: 15m
    RUNNER_AFTER_SCRIPT_TIMEOUT: 10m
  script:
    - "I am allowed to run for min(15m, remaining job timeout)."
  after_script:
    - "I am allowed to run for min(10m, remaining job timeout)."

job-artifact-upload-on-timeout:
  timeout: 1h                           # set job timeout to 1 hour
  variables:
     RUNNER_SCRIPT_TIMEOUT: 50m         # only allow script to run for 50 minutes
  script:
    - long-running-process > output.txt # will be terminated after 50m

  artifacts: # artifacts will have roughly ~10m to upload
    paths:
      - output.txt
    when: on_failure # on_failure because script termination after a timeout is treated as a failure

确保 `after_script` 执行

为了使 after_script 成功运行，RUNNER_SCRIPT_TIMEOUT + RUNNER_AFTER_SCRIPT_TIMEOUT 的总和不得超过作业配置的超时时间。

以下示例显示了如何配置超时时间以确保 after_script 在主脚本超时后仍能运行：

job-with-script-timeouts:
  timeout: 5m
  variables:
    RUNNER_SCRIPT_TIMEOUT: 1m
    RUNNER_AFTER_SCRIPT_TIMEOUT: 1m
  script:
    - echo "Starting build..."
    - sleep 120 # Wait 2 minutes to trigger timeout. Script aborts after 1 minute due to RUNNER_SCRIPT_TIMEOUT.
    - echo "Build finished."
  after_script:
    - echo "Starting Clean-up..."
    - sleep 15 # Wait just a few seconds. Runs successfully because it's within RUNNER_AFTER_SCRIPT_TIMEOUT.
    - echo "Clean-up finished."

script 被 RUNNER_SCRIPT_TIMEOUT 取消，但 after_script 成功运行，因为它只需 15 秒，少于 RUNNER_AFTER_SCRIPT_TIMEOUT 和作业的 timeout 值。

保护敏感信息

使用实例 runner 时，安全风险更大，因为它们默认对极狐GitLab 实例中的所有群组和项目可用。Runner 执行器和文件系统配置影响安全性。访问 runner 主机环境的用户可以查看 runner 执行的代码和 runner 身份验证。例如，拥有 runner 身份验证令牌的用户可以克隆 runner 并在矢量攻击中提交虚假作业。

配置长轮询

为了减少作业排队时间和减轻极狐GitLab 服务器的负载，请配置长轮询。

在派生项目中使用实例 runner

当项目被派生时，与作业相关的作业设置会被复制。如果您为项目配置了实例 runner，并且用户派生了该项目，则实例 runner 服务于该项目的作业。

由于已知问题，如果派生项目的 runner 设置与新项目命名空间不匹配，则会显示以下消息：An error occurred while forking the project. Please try again.。

要解决此问题，请确保派生项目和新命名空间中的实例 runner 设置一致。

如果在派生项目上启用了实例 runner，则在新命名空间上也应启用。
如果在派生项目上禁用了实例 runner，则在新命名空间上也应禁用。

重置项目的 runner 注册令牌（已弃用）

在极狐GitLab 15.6 中，传递 runner 注册令牌和支持某些配置参数的选项已弃用，计划在极狐GitLab 20.0 中移除。使用 runner 创建工作流程生成身份验证令牌以注册 runner。此过程提供了 runner 所有权的完整可追溯性，并增强了 runner 队列的安全性。有关更多信息，请参阅迁移到新的 runner 注册工作流程。

如果您认为项目的注册令牌被泄露，您应该重置它。注册令牌可以用于为项目注册另一个 runner。然后，该新 runner 可以用于获取密钥变量的值或克隆项目代码。

要重置注册令牌：

在左侧边栏，选择 搜索或转到 并找到您的项目。
选择 设置 > CI/CD。
展开 Runner。
在 新项目 runner 右侧，选择垂直省略号 ({{< icon name=”ellipsis_v” >}})。
选择 重置注册令牌。
选择 重置令牌。

在您重置注册令牌后，该令牌不再有效，也无法注册任何新的 runner 到项目。您还应该更新您用来配置和注册新值的工具中的注册令牌。

身份验证令牌安全性

在极狐GitLab 15.3 中引入，使用名为 enforce_runner_token_expires_at 的功能标志。默认禁用。
在极狐GitLab 15.5 中 GA。功能标志 enforce_runner_token_expires_at 已移除。

每个 runner 使用 runner 身份验证令牌连接并验证与极狐GitLab 实例的身份。

为了帮助防止令牌被泄露，您可以让令牌在指定的时间间隔自动轮换。当令牌轮换时，它们会为每个 runner 更新，无论 runner 的状态是 在线 还是 离线。

不应需要手动干预，并且不应影响任何正在运行的作业。有关令牌轮换的更多信息，请参阅 Runner 身份验证令牌在轮换时不会更新。

如果您需要手动更新 runner 身份验证令牌，您可以运行命令来重置令牌。

重置 runner 配置身份验证令牌

如果 runner 的身份验证令牌被泄露，攻击者可能会用它来克隆 runner。

要重置 runner 配置身份验证令牌：

删除 runner：
- 删除实例 runner。
- 删除群组 runner。
- 删除项目 runner。
创建一个新的 runner，以便为其分配一个新的 runner 身份验证令牌：
- 创建实例 runner。
- 创建群组 runner。
- 创建项目 runner。
可选。要验证以前的 runner 身份验证令牌是否已被撤销，请使用 Runner API。

要重置 runner 配置身份验证令牌，您还可以使用 Runner API。

自动轮换 runner 身份验证令牌

您可以指定一个间隔来轮换 runner 身份验证令牌。定期轮换 runner 身份验证令牌有助于最大限度地减少通过泄露的令牌对极狐GitLab 实例进行未经授权访问的风险。

先决条件：

Runner 必须使用极狐GitLab Runner 15.3 或更高版本。
您必须是管理员。

要自动轮换 runner 身份验证令牌：

在左侧边栏底部，选择 管理员。
选择 设置 > CI/CD。
展开 持续集成和部署。
设置 Runner 过期 时间，留空表示没有过期。
选择 保存更改。

在间隔到期之前，runner 会自动请求新的 runner 身份验证令牌。有关令牌轮换的更多信息，请参阅 Runner 身份验证令牌在轮换时不会更新。

防止 runner 泄露敏感信息

为了确保 runner 不泄露敏感信息，您可以配置它们仅在受保护分支上运行作业，或具有受保护标签的作业。

配置为在受保护分支上运行作业的 runner 不能在合并请求流水线中运行作业。

对于实例 runner

先决条件：

您必须是管理员。

在左侧边栏底部，选择 管理员。
选择 CI/CD > Runner。
在要保护的 runner 右侧，选择编辑 ({{< icon name=”pencil” >}})。
选择 受保护 复选框。
选择 保存更改。

对于群组 runner

先决条件：

您必须具有群组的所有者角色。

在左侧边栏，选择 搜索或转到 并找到您的群组。
选择 构建 > Runner。
在要保护的 runner 右侧，选择编辑 ({{< icon name=”pencil” >}})。
选择 受保护 复选框。
选择 保存更改。

对于项目 runner

先决条件：

您必须具有项目的所有者角色。

在左侧边栏，选择 搜索或转到 并找到您的项目。
选择 设置 > CI/CD。
展开 Runner。
在要保护的 runner 右侧，选择编辑 ({{< icon name=”pencil” >}})。
选择 受保护 复选框。
选择 保存更改。

控制 runner 可以运行的作业

您可以使用标签来控制 runner 可以运行的作业。例如，您可以为具有运行 Rails 测试套件所需依赖项的 runner 指定 rails 标签。

极狐GitLab CI/CD 标签与 Git 标签不同。极狐GitLab CI/CD 标签与 runner 关联。Git 标签与提交关联。

对于实例 runner

先决条件：

您必须是管理员。

要控制实例 runner 可以运行的作业：

在左侧边栏底部，选择 管理员。
选择 CI/CD > Runner。
在要编辑的 runner 右侧，选择编辑 ({{< icon name=”pencil” >}})。
设置 runner 以运行带标签或不带标签的作业：
- 要运行带标签的作业，在标签字段中输入作业标签，以逗号分隔。例如，macos、rails。
- 要运行不带标签的作业，选择 运行不带标签的作业 复选框。
选择 保存更改。

对于群组 runner

先决条件：

您必须具有群组的所有者角色。

要控制群组 runner 可以运行的作业：

在左侧边栏，选择 搜索或转到 并找到您的群组。
选择 构建 > Runner。
在要编辑的 runner 右侧，选择编辑 ({{< icon name=”pencil” >}})。
设置 runner 以运行带标签或不带标签的作业：
- 要运行带标签的作业，在标签字段中输入作业标签，以逗号分隔。例如，macos、ruby。
- 要运行不带标签的作业，选择 运行不带标签的作业 复选框。
选择 保存更改。

对于项目 runner

先决条件：

您必须具有项目的所有者角色。

要控制项目 runner 可以运行的作业：

在左侧边栏，选择 搜索或转到 并找到您的项目。
选择 设置 > CI/CD。
展开 Runner。
在要编辑的 runner 右侧，选择编辑 ({{< icon name=”pencil” >}})。
设置 runner 以运行带标签或不带标签的作业：
- 要运行带标签的作业，在标签字段中输入作业标签，以逗号分隔。例如，macos、ruby。
- 要运行不带标签的作业，选择 运行不带标签的作业 复选框。
选择 保存更改。

runner 如何使用标签

runner 仅运行带标签的作业

以下示例说明了 runner 仅运行带标签作业可能产生的影响。

示例 1：

runner 配置为仅运行带标签的作业，并具有 docker 标签。
执行具有 hello 标签的作业并卡住。

示例 2：

runner 配置为仅运行带标签的作业，并具有 docker 标签。
执行具有 docker 标签的作业并运行。

示例 3：

runner 配置为仅运行带标签的作业，并具有 docker 标签。
执行没有定义标签的作业并卡住。

runner 允许运行不带标签的作业

以下示例说明了 runner 设置为运行带标签和不带标签作业可能产生的影响。

示例 1：

runner 配置为运行不带标签的作业，并具有 docker 标签。
执行没有定义标签的作业并运行。
执行第二个定义了 docker 标签的作业并运行。

示例 2：

runner 配置为运行不带标签的作业，并没有定义标签。
执行没有定义标签的作业并运行。
执行第二个定义了 docker 标签的作业并卡住。

runner 和作业具有多个标签

匹配作业和 runner 的选择逻辑基于作业中定义的 标签 列表。

以下示例说明了 runner 和作业具有多个标签的影响。要选择 runner 运行作业，它必须具有作业脚本块中定义的所有标签。

示例 1：

runner 配置了 [docker, shell, gpu] 标签。
作业具有 [docker, shell, gpu] 标签，并执行和运行。

示例 2：

runner 配置了 [docker, shell, gpu] 标签。
作业具有 [docker, shell] 标签，并执行和运行。

示例 3：

runner 配置了 [docker, shell] 标签。
作业具有 [docker, shell, gpu] 标签，并未执行。

使用标签在不同平台上运行作业

您可以使用标签在不同平台上运行不同的作业。例如，如果您有一个带有 osx 标签的 OS X runner 和一个带有 windows 标签的 Windows runner，则可以在每个平台上运行一个作业。

更新 .gitlab-ci.yml 中的 标签 字段：

windows job:
  stage: build
  tags:
    - windows
  script:
    - echo Hello, %USERNAME%!

osx job:
  stage: build
  tags:
    - osx
  script:
    - echo "Hello, $USER!"

在标签中使用 CI/CD 变量

在 .gitlab-ci.yml 文件中，使用 标签 中的 CI/CD 变量进行动态 runner 选择：

variables:
  KUBERNETES_RUNNER: kubernetes

  job:
    tags:
      - docker
      - $KUBERNETES_RUNNER
    script:
      - echo "Hello runner selector feature"

使用变量配置 runner 行为

您可以使用 CI/CD 变量全局或针对单个作业配置 runner 的 Git 行为：

GIT_STRATEGY
GIT_SUBMODULE_STRATEGY
GIT_CHECKOUT
GIT_CLEAN_FLAGS
GIT_FETCH_EXTRA_FLAGS
GIT_SUBMODULE_UPDATE_FLAGS
GIT_SUBMODULE_FORCE_HTTPS
GIT_DEPTH（浅克隆）
GIT_SUBMODULE_DEPTH
GIT_CLONE_PATH（自定义构建目录）
TRANSFER_METER_FREQUENCY（产物/缓存计量器更新频率）
ARTIFACT_COMPRESSION_LEVEL（产物压缩级别）
CACHE_COMPRESSION_LEVEL（缓存压缩级别）
CACHE_REQUEST_TIMEOUT（缓存请求超时）
RUNNER_SCRIPT_TIMEOUT
RUNNER_AFTER_SCRIPT_TIMEOUT
AFTER_SCRIPT_IGNORE_ERRORS

您还可以使用变量配置 runner 尝试运行某些作业执行阶段的次数。

使用 Kubernetes 执行器时，您可以使用变量来覆盖 Kubernetes CPU 和内存分配的请求和限制。

Git 策略

GIT_STRATEGY 变量配置构建目录的准备方式和存储库内容的获取方式。您可以在 variables 部分中全局或针对单个作业设置此变量。

variables:
  GIT_STRATEGY: clone

可能的值有 clone、fetch、none 和 empty。如果未指定值，作业使用项目的流水线设置。

clone 是最慢的选项。它为每个作业从头开始克隆存储库，确保本地工作副本始终干净。如果找到现有工作树，则在克隆之前将其删除。

fetch 更快，因为它重用本地工作副本（如果不存在则返回 clone）。使用 git clean 撤销上一个作业所做的更改，使用 git fetch 获取在上一个作业运行后进行的提交。

然而，fetch 确实需要访问先前的工作树。这在使用 shell 或 docker 执行器时效果很好，因为它们尝试保留工作树并默认尝试重用它们。

在使用 Docker Machine 执行器时有其局限性。

Git 策略为 none 时，也重用本地工作副本，但跳过极狐GitLab 通常执行的所有 Git 操作。如果存在，极狐GitLab Runner 预克隆脚本也会被跳过。此策略可能意味着您需要将 fetch 和 checkout 命令添加到您的 .gitlab-ci.yml 脚本中。

它可用于专门处理产物的作业，例如部署作业。Git 存储库数据可能存在，但可能已过期。您应该仅依赖于从缓存或产物带入本地工作副本的文件。注意，来自先前流水线的缓存和产物文件可能仍然存在。

与 none 不同，empty Git 策略删除并重新创建专用构建目录，然后下载缓存或产物文件。使用此策略，极狐GitLab Runner 挂钩脚本仍会运行（如果提供），以允许进一步自定义行为。使用 empty Git 策略时：

您不需要存储库数据存在。
您希望每次作业运行时都有一个干净、可控或自定义的初始状态。

Git 子模块策略

GIT_SUBMODULE_STRATEGY 变量用于控制在构建前获取代码时是否/如何包含 Git 子模块。您可以在 variables 部分中全局或针对单个作业设置它们。

三个可能的值是 none、normal 和 recursive：

none 表示在获取项目代码时不包含子模块。这一设置与 1.10 之前版本的默认行为一致。

normal 表示仅包含顶级子模块。等效于：

git submodule sync
git submodule update --init

recursive 表示包含所有子模块（包括子模块的子模块）。此功能需要 Git v1.8.1 及更高版本。使用不基于 Docker 的执行器时，请确保 Git 版本满足该要求。等效于：
```
git submodule sync --recursive
git submodule update --init --recursive
```

为了使此功能正常工作，子模块必须在 .gitmodules 中配置为：

公共可访问存储库的 HTTP(S) URL，或
相同极狐GitLab 服务器上另一个存储库的相对路径。请参阅 Git 子模块文档。

您可以提供额外的标志来控制高级行为，使用 GIT_SUBMODULE_UPDATE_FLAGS。

Git 检出

当 GIT_STRATEGY 设置为 clone 或 fetch 时，可以使用 GIT_CHECKOUT 变量指定是否应该运行 git checkout。如果未指定，默认值为 true。您可以在 variables 部分中全局或针对单个作业设置它们。

如果设置为 false，runner：

在进行 fetch 时 - 更新存储库并将工作副本保留在当前修订版上，
在进行 clone 时 - 克隆存储库并将工作副本保留在默认分支上。

如果 GIT_CHECKOUT 设置为 true，clone 和 fetch 工作方式相同。runner 检出与 CI 流水线相关的修订版的工作副本：

variables:
  GIT_STRATEGY: clone
  GIT_CHECKOUT: "false"
script:
  - git checkout -B master origin/master
  - git merge $CI_COMMIT_SHA

Git 清理标志

GIT_CLEAN_FLAGS 变量用于控制在检出源代码后 git clean 的默认行为。您可以在 variables 部分中全局或针对单个作业设置它。

GIT_CLEAN_FLAGS 接受 git clean 命令的所有可能选项。

如果指定了 GIT_CHECKOUT: "false"，则禁用 git clean。

如果 GIT_CLEAN_FLAGS 是：

未指定，则 git clean 标志默认为 -ffdx。
赋值为 none，则不执行 git clean。

例如：

variables:
  GIT_CLEAN_FLAGS: -ffdx -e cache/
script:
  - ls -al cache/

Git 获取额外标志

使用 GIT_FETCH_EXTRA_FLAGS 变量控制 git fetch 的行为。您可以在 variables 部分中全局或针对单个作业设置它。

GIT_FETCH_EXTRA_FLAGS 接受 git fetch 命令的所有选项。然而，GIT_FETCH_EXTRA_FLAGS 标志在默认标志之后附加，无法修改。

默认标志是：

GIT_DEPTH。
refspecs 的列表。
名为 origin 的远程。

如果 GIT_FETCH_EXTRA_FLAGS 是：

未指定，则 git fetch 标志默认为 --prune --quiet，以及默认标志。
赋值为 none，则 git fetch 仅使用默认标志执行。

例如，默认标志是 --prune --quiet，因此您可以通过仅覆盖 --prune 来使 git fetch 更详细：

variables:
  GIT_FETCH_EXTRA_FLAGS: --prune
script:
  - ls -al cache/

上述配置导致 git fetch 被这样调用：

git fetch origin $REFSPECS --depth 50  --prune

其中 $REFSPECS 是由极狐GitLab 内部提供给 runner 的值。

从 CI 作业中同步或排除特定子模块

使用 GIT_SUBMODULE_PATHS 变量控制哪些子模块必须同步或更新。您可以在 variables 部分中全局或针对单个作业设置它。

路径语法与 git submodule 相同：

要同步和更新特定路径：

variables:
   GIT_SUBMODULE_PATHS: submoduleA submoduleB

要排除特定路径：

variables:
   GIT_SUBMODULE_PATHS: ":(exclude)submoduleA :(exclude)submoduleB"

Git 忽略嵌套路径。要忽略嵌套子模块，请排除父子模块，然后在作业脚本中手动克隆它。例如，git clone <repo> --recurse-submodules=':(exclude)nested-submodule'。确保将字符串用单引号括起来，以便成功解析 YAML。

Git 子模块更新标志

使用 GIT_SUBMODULE_UPDATE_FLAGS 变量控制 git submodule update 的行为，当 GIT_SUBMODULE_STRATEGY 设置为 normal 或 recursive 时。您可以在 variables 部分中全局或针对单个作业设置它。

GIT_SUBMODULE_UPDATE_FLAGS 接受 git submodule update子命令的所有选项。然而，GIT_SUBMODULE_UPDATE_FLAGS 标志在几个默认标志之后附加：

--init，如果 GIT_SUBMODULE_STRATEGY 设置为 normal 或 recursive。
--recursive，如果 GIT_SUBMODULE_STRATEGY 设置为 recursive。
GIT_DEPTH。请参阅下面的默认值。

Git 尊重参数列表中标志的最后一次出现，因此在 GIT_SUBMODULE_UPDATE_FLAGS 中手动提供它们会覆盖这些默认标志。

例如，您可以使用此变量来：

获取最新的远程 HEAD 而不是仓库中跟踪的提交（默认），以自动更新所有子模块，使用 --remote 标志。
使用 --jobs 4 标志加速检出，通过多个并行作业获取子模块。

variables:
  GIT_SUBMODULE_STRATEGY: recursive
  GIT_SUBMODULE_UPDATE_FLAGS: --remote --jobs 4
script:
  - ls -al .git/modules/

上述配置导致 git submodule update 被这样调用：

git submodule update --init --depth 50 --recursive --remote --jobs 4

您应该了解使用 --remote 标志对构建的安全性、稳定性和可重现性可能产生的影响。在大多数情况下，最好明确跟踪子模块提交，并使用自动修复/依赖机器人更新它们。

--remote 标志不是检出子模块的提交修订所必需的。仅当您希望自动更新子模块到其最新远程版本时使用此标志。

--remote 的行为取决于您的 Git 版本。当超级项目的 .gitmodules 中的分支与子模块存储库的默认分支不同时时，某些 Git 版本可能会失败并显示以下错误：

fatal: Unable to find refs/remotes/origin/<branch> revision in submodule path '<submodule-path>'

runner 实现了一个 “最佳努力” 回退，当子模块更新失败时尝试提取远程引用。

如果此回退不适用于您的 Git 版本，请尝试以下解决方案之一：

更新子模块存储库的默认分支以匹配超级项目中的 .gitmodules 中设置的分支。
将 GIT_SUBMODULE_DEPTH 设置为 0。
单独更新子模块并从 GIT_SUBMODULE_UPDATE_FLAGS 中删除 --remote 标志。

将子模块 URL 重写为 HTTPS

在极狐GitLab Runner 15.11 中引入。

使用 GIT_SUBMODULE_FORCE_HTTPS 变量强制重写所有 Git 和 SSH 子模块 URL 为 HTTPS。即使它们使用 Git 或 SSH 协议配置，也可以克隆使用绝对 URL 的子模块。

variables:
  GIT_SUBMODULE_STRATEGY: recursive
  GIT_SUBMODULE_FORCE_HTTPS: "true"

启用时，极狐GitLab Runner 使用 CI/CD 作业令牌克隆子模块。该令牌使用执行作业的用户权限，不需要 SSH 凭据。

浅克隆

您可以使用 GIT_DEPTH 指定获取和克隆的深度。GIT_DEPTH 进行存储库的浅克隆，可以显著加快克隆速度。对于具有大量提交或旧的大型二进制文件的存储库来说，它可能很有帮助。该值传递给 git fetch 和 git clone。

新创建的项目自动具有默认 git depth 值为 50。

如果您使用深度为 1 并且有一个作业队列或重试作业，作业可能会失败。

Git 获取和克隆基于引用，例如分支名称，因此 runner 无法克隆特定提交 SHA。如果多个作业在队列中，或者您重试旧作业，则需要测试的提交必须位于克隆的 Git 历史中。设置过小的 GIT_DEPTH 值可能无法运行这些旧提交，并在作业日志中显示 unresolved reference。您应该考虑将 GIT_DEPTH 更改为更高的值。

依赖于 git describe 的作业在设置 GIT_DEPTH 时可能无法正常工作，因为只有部分 Git 历史存在。

要仅获取或克隆最后 3 次提交：

variables:
  GIT_DEPTH: "3"

您可以在 variables 部分中全局或针对单个作业设置它。

Git 子模块深度

在极狐GitLab Runner 15.5 中引入。

使用 GIT_SUBMODULE_DEPTH 变量指定获取和克隆子模块的深度，当 GIT_SUBMODULE_STRATEGY 设置为 normal 或 recursive 时。您可以在 variables 部分中全局或针对单个作业设置它。

设置 GIT_SUBMODULE_DEPTH 变量时，它会覆盖子模块的 GIT_DEPTH 设置。

要仅获取或克隆最后 3 次提交：

variables:
  GIT_SUBMODULE_DEPTH: 3

自定义构建目录

默认情况下，极狐GitLab Runner 在 $CI_BUILDS_DIR 目录的唯一子路径中克隆存储库。然而，您的项目可能需要代码位于特定目录中（例如，Go 项目）。在这种情况下，您可以指定 GIT_CLONE_PATH 变量来告诉 runner 克隆存储库的目录：

variables:
  GIT_CLONE_PATH: $CI_BUILDS_DIR/project-name

test:
  script:
    - pwd

GIT_CLONE_PATH 必须始终位于 $CI_BUILDS_DIR 内。设置 $CI_BUILDS_DIR 的目录取决于执行器和 runner.builds_dir 设置的配置。

只有在 runner 的配置中启用 custom_build_dir 时才能使用。

处理并发

使用并发大于 1 的执行器可能导致失败。如果 builds_dir 在作业之间共享，则多个作业可能在同一目录中工作。

runner 不会尝试防止这种情况。管理员和开发人员需要遵循 runner 配置的要求。

为了避免这种情况，您可以在 $CI_BUILDS_DIR 中使用唯一路径，因为 runner 暴露了两个附加变量，提供了并发的唯一 ID：

$CI_CONCURRENT_ID：在给定执行器中运行的所有作业的唯一 ID。
$CI_CONCURRENT_PROJECT_ID：在给定执行器和项目中运行的所有作业的唯一 ID。

在任何场景和任何执行器上工作良好的最稳定配置是使用 $CI_CONCURRENT_ID 在 GIT_CLONE_PATH 中。例如：

variables:
  GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/project-name

test:
  script:
    - pwd -P

$CI_CONCURRENT_PROJECT_ID 应与 $CI_PROJECT_PATH 一起使用。$CI_PROJECT_PATH 提供存储库的路径，格式为 group/subgroup/project。例如：

variables:
  GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_PATH

test:
  script:
    - pwd -P

嵌套路径

GIT_CLONE_PATH 的值展开一次。您无法在此值中嵌套变量。

例如，您在 .gitlab-ci.yml 文件中定义以下两个变量：

variables:
  GOPATH: $CI_BUILDS_DIR/go
  GIT_CLONE_PATH: $GOPATH/src/namespace/project

GIT_CLONE_PATH 的值被扩展为一次性 $CI_BUILDS_DIR/go/src/namespace/project，结果失败，因为 $CI_BUILDS_DIR 未被扩展。

忽略 `after_script` 中的错误

您可以在作业中使用 after_script 来定义一组命令，这些命令应在作业的 before_script 和 script 部分之后运行。无论脚本终止状态（失败或成功），after_script 命令都会运行。

默认情况下，极狐GitLab Runner 忽略 after_script 运行时发生的任何错误。要设置作业在 after_script 运行时立即因错误而失败，请将 CI/CD 变量 AFTER_SCRIPT_IGNORE_ERRORS 设置为 false。例如：

variables:
  AFTER_SCRIPT_IGNORE_ERRORS: false

作业阶段尝试次数

您可以设置运行作业尝试执行以下阶段的次数：

变量	描述
`ARTIFACT_DOWNLOAD_ATTEMPTS`	下载运行作业的产物的尝试次数
`EXECUTOR_JOB_SECTION_ATTEMPTS`	在作业中运行某个部分的尝试次数，出现 `No Such Container` 错误（仅限 Docker 执行器）。
`GET_SOURCES_ATTEMPTS`	获取运行作业源的尝试次数
`RESTORE_CACHE_ATTEMPTS`	恢复运行作业缓存的尝试次数

默认情况下，是一次性尝试。

示例：

variables:
  GET_SOURCES_ATTEMPTS: 3

您可以在 variables 部分中全局或每个作业设置它们。

JihuLab.com 实例 runner 上不可用的系统调用

JihuLab.com 实例 runner 运行在 CoreOS 上。这意味着您不能使用某些系统调用，如 C 标准库中的 getlogin。

产物和缓存设置

产物和缓存设置控制产物和缓存的压缩比。使用这些设置来指定作业生成的归档大小。

在慢速网络上，较小的归档上传可能更快。
在带宽和存储不是问题的快速网络上，使用最快的压缩比进行上传可能更快，尽管生成的归档较大。

为了让极狐GitLab Pages 提供 HTTP Range 请求，产物应使用 ARTIFACT_COMPRESSION_LEVEL: fastest 设置，因为只有未压缩的 zip 归档支持此功能。

可以启用一个计量器来提供上传和下载的传输率。

您可以使用 CACHE_REQUEST_TIMEOUT 设置来设置缓存上传和下载的最大时间。使用此设置，当慢速缓存上传显著增加作业持续时间时。

variables:
  # 每 2 秒输出上传和下载进度
  TRANSFER_METER_FREQUENCY: "2s"

  # 对产物使用快速压缩，结果是较大的归档
  ARTIFACT_COMPRESSION_LEVEL: "fast"

  # 对缓存不使用压缩
  CACHE_COMPRESSION_LEVEL: "fastest"

  # 设置缓存上传和下载的最大持续时间
  CACHE_REQUEST_TIMEOUT: 5

变量	描述
`TRANSFER_METER_FREQUENCY`	指定打印计量器的传输速率频率。可以设置为持续时间（例如，`1s` 或 `1m30s`）。设置为 `0` 禁用计量器（默认）。设置后，流水线显示产物和缓存上传和下载的进度计量器。
`ARTIFACT_COMPRESSION_LEVEL`	要调整压缩比，设置为 `fastest`、`fast`、`default`、`slow` 或 `slowest`。此设置仅与 Fastzip 归档器一起工作，因此极狐GitLab Runner 功能标志 `FF_USE_FASTZIP` 也必须启用。
`CACHE_COMPRESSION_LEVEL`	要调整压缩比，设置为 `fastest`、`fast`、`default`、`slow` 或 `slowest`。此设置仅与 Fastzip 归档器一起工作，因此极狐GitLab Runner 功能标志 `FF_USE_FASTZIP` 也必须启用。
`CACHE_REQUEST_TIMEOUT`	配置单个作业的缓存上传和下载操作的最大持续时间，以分钟为单位。默认是 `10` 分钟。

产物来源元数据

在极狐GitLab Runner 15.1 中引入。

runner 可以生成 SLSA Provenance 并生成一个 SLSA Statement，将来源绑定到所有构建产物。该声明称为产物来源元数据。

要启用产物来源元数据，请将环境变量 RUNNER_GENERATE_ARTIFACTS_METADATA 设置为 true。您可以全局或为单个作业设置变量：

variables:
  RUNNER_GENERATE_ARTIFACTS_METADATA: "true"

job1:
  variables:
    RUNNER_GENERATE_ARTIFACTS_METADATA: "true"

元数据以纯文本 .json 文件格式呈现，并与产物一起存储。文件名是 {ARTIFACT_NAME}-metadata.json。ARTIFACT_NAME 是在 .gitlab-ci.yml 文件中定义的产物名称。如果名称未定义，默认文件名为 artifacts-metadata.json。

来源元数据格式

产物来源元数据以 in-toto v0.1 Statement 格式生成。它包含以 SLSA 1.0 Provenance 格式生成的来源谓词。

默认情况下填充以下字段：

字段	值
`_type`	`https://in-toto.io/Statement/v0.1`
`subject.name`	产物的文件名。
`subject.digest.sha256`	产物的 `sha256` 校验和。
`predicateType`	`https://slsa.dev/provenance/v1`
`predicate.buildDefinition.buildType`	`https://jihulab.com/gitlab-cn/gitlab-runner/-/blob/{GITLAB_RUNNER_VERSION}/PROVENANCE.md`。例如，v15.0.0
`predicate.runDetails.builder.id`	指向 runner 详情页面的 URI，例如，`https://jihulab.com/gitlab-cn/www-gitlab-com/-/runners/3785264`。
`predicate.buildDefinition.externalParameters`	在构建命令执行期间可用的任何 CI/CD 或环境变量的名称。值始终表示为空字符串以保护机密。
`predicate.buildDefinition.externalParameters.source`	项目的 URL。
`predicate.buildDefinition.externalParameters.entryPoint`	触发构建的 CI/CD 作业名称。
`predicate.buildDefinition.internalParameters.name`	runner 的名称。
`predicate.buildDefinition.internalParameters.executor`	runner 执行器。
`predicate.buildDefinition.internalParameters.architecture`	CI/CD 作业运行的架构。
`predicate.buildDefinition.internalParameters.job`	触发构建的 CI/CD 作业 ID。
`predicate.buildDefinition.resolvedDependencies[0].uri`	项目的 URL。
`predicate.buildDefinition.resolvedDependencies[0].digest.sha256`	项目的提交修订。
`predicate.runDetails.metadata.invocationID`	触发构建的 CI/CD 作业 ID。
`predicate.runDetails.metadata.startedOn`	构建开始的时间。此字段是 `RFC3339` 格式。
`predicate.runDetails.metadata.finishedOn`	构建结束的时间。由于元数据生成发生在构建期间，此时间略早于极狐GitLab 报告的时间。此字段是 `RFC3339` 格式。

暂存目录

在极狐GitLab Runner 15.0 中引入。

如果您不想在系统的默认临时目录中归档缓存和产物，可以指定一个不同的目录。

如果您的系统默认临时路径有约束，您可能需要更改目录。如果您使用快速磁盘作为目录位置，它还可以提高性能。

要更改目录，请在您的 CI 作业中将 ARCHIVER_STAGING_DIR 设置为变量，或在注册 runner 时使用 runner 变量 (gitlab register --env ARCHIVER_STAGING_DIR=<dir>)。

您指定的目录用于在提取之前下载产物的位置。如果使用 fastzip 归档器，此位置也用作归档时的临时空间。

配置 `fastzip` 以提高性能

在极狐GitLab Runner 15.0 中引入。

为了优化 fastzip，确保启用了 FF_USE_FASTZIP 标志。然后使用以下任意环境变量。

变量	描述
`FASTZIP_ARCHIVER_CONCURRENCY`	并发压缩的文件数。默认是可用的 CPU 数量。
`FASTZIP_ARCHIVER_BUFFER_SIZE`	每个文件并发分配的缓冲区大小。超过该数量的数据转移到临时空间。默认是 2 MiB。
`FASTZIP_EXTRACTOR_CONCURRENCY`	并发解压的文件数。默认是可用的 CPU 数量。

zip 归档中的文件是顺序追加的。这使得并发压缩具有挑战性。fastzip 通过首先将文件并发压缩到磁盘，然后将结果顺序复制回 zip 归档来解决此限制。

为了避免将较小文件写入磁盘并读取内容，每个并发使用一个小缓冲区。此设置可以通过 FASTZIP_ARCHIVER_BUFFER_SIZE 控制。此缓冲区的默认大小为 2 MiB，因此，并发 16 分配 32 MiB。超过缓冲区大小的数据会写入磁盘并从磁盘读取。因此，不使用缓冲区，FASTZIP_ARCHIVER_BUFFER_SIZE: 0，并且仅使用临时空间是一个有效选项。

FASTZIP_ARCHIVER_CONCURRENCY 控制并发压缩的文件数。如上所述，此设置因此可以增加使用的内存量。它还可以增加写入临时空间的数据量。默认是可用的 CPU 数量，但由于内存影响，这可能不是最佳设置。

FASTZIP_EXTRACTOR_CONCURRENCY 控制一次解压的文件数。zip 归档中的文件可以从并发读取，因此除了提取器需要的内存外，不会额外分配内存。这默认是可用的 CPU 数量。

设置最大作业超时时间

对于实例 runner

对于群组 runner

对于项目 runner

最大作业超时时间如何工作

设置 script 和 after_script 超时时间

确保 after_script 执行

保护敏感信息

配置长轮询

在派生项目中使用实例 runner

重置项目的 runner 注册令牌（已弃用）

身份验证令牌安全性

重置 runner 配置身份验证令牌

自动轮换 runner 身份验证令牌

防止 runner 泄露敏感信息

对于实例 runner

对于群组 runner

对于项目 runner

控制 runner 可以运行的作业

对于实例 runner

对于群组 runner

对于项目 runner

runner 如何使用标签

runner 仅运行带标签的作业

runner 允许运行不带标签的作业

runner 和作业具有多个标签

使用标签在不同平台上运行作业

在标签中使用 CI/CD 变量

使用变量配置 runner 行为

Git 策略

Git 子模块策略

Git 检出

Git 清理标志

Git 获取额外标志

从 CI 作业中同步或排除特定子模块

Git 子模块更新标志

将子模块 URL 重写为 HTTPS

浅克隆

Git 子模块深度

自定义构建目录

处理并发

嵌套路径

忽略 after_script 中的错误

作业阶段尝试次数

JihuLab.com 实例 runner 上不可用的系统调用

产物和缓存设置

产物来源元数据

来源元数据格式

暂存目录

配置 fastzip 以提高性能

设置 `script` 和 `after_script` 超时时间

确保 `after_script` 执行

忽略 `after_script` 中的错误

配置 `fastzip` 以提高性能