手动清除 runner 缓存
设置 runner 的最大作业超时
小心敏感信息
确定 runner 的 IP 地址
- 确定共享 runner 的 IP 地址
- 确定特定 runner 的 IP 地址
使用标签来控制 runner 可以运行哪些作业
使用变量配置 runner 行为
产物和缓存设置

配置 runners

如果您已经安装了自己的 runner，则可以在极狐GitLab 中配置和保护它们。

手动清除 runner 缓存

阅读清除缓存。

设置 runner 的最大作业超时

对于每个 runner，您可以指定最大作业超时。如果此超时小于项目定义的超时，则此超时设置优先。

此功能可用于防止您的共享 runner 被具有长时间超时（例如，一周）的作业的项目压倒。

要设置最大作业超时：

在项目中，转到 设置 > CI/CD > Runners。
选择您的特定 runner，来编辑设置。
在 最大作业超时 下输入一个值。必须是 10 分钟或更长时间。如果未定义，则使用项目的作业超时设置。
选择 保存修改。

此功能的工作原理：

示例 1 - Runner 超时大于项目超时

您将 runner 的 最大作业超时 设置为 24 小时
您将项目的 CI/CD 超时 设置为 2 小时
启动作业
如果运行时间较长，作业会在 2 小时后超时

示例 2 - 未配置 runner 超时

您从 runner 中删除 最大作业超时 配置
您将项目的 CI/CD 超时 设置为 2 小时
启动作业
如果运行时间较长，作业会在 2 小时后超时

示例 3 - Runner 超时小于项目超时

您将 runner 的 最大作业超时 设置为 30 分钟
您将项目的 CI/CD 超时 设置为 2 小时
启动作业
如果运行时间较长，作业会在 30 分钟后超时

小心敏感信息

对于某些 runner executors，如果您可以在 runner 上运行作业，您可以获得对文件系统的完全访问权限，因此可以访问它运行的任何代码，以及 runner 的令牌。使用共享 runner，这意味着在 runner 上运行作业的任何人都可以访问在 runner 上运行的任何其他人的代码。

此外，由于您可以访问 runner 令牌，因此可以创建 runner 的克隆并提交虚假作业。

通过在大型公开实例上限制共享 runner 的使用、控制对实例的访问以及使用更安全的 runner executors，可以轻松避免上述情况。

防止 runners 泄露敏感信息

您可以保护 runner，使他们不会泄露敏感信息。当 runner 受到保护时，runner 只会选择在受保护的分支或受保护的标签上创建的作业，忽略其它作业。

保护或取消保护 runner：

转到项目的 设置 > CI/CD 并展开 Runners 部分。
找到您想保护或取消保护的 runner。确保它已启用。
点击铅笔按钮。
勾选 受保护 选项。
单击 保存修改。

派生

每当一个项目被派生时，它都会复制与其相关的作业的设置。这意味着，如果您为项目设置了共享 runner 并且有人派生了该项目，则共享 runner 将为该项目的作业提供服务。

重置项目的 runner 注册令牌

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

要重置注册令牌：

进入项目的 设置 > CI/CD。
展开 General pipelines settings 部分。
找到 Runner 令牌 表单字段，然后单击 显示值 按钮。
删除值并保存表格。
页面刷新后，展开 Runners settings 部分并检查注册令牌 - 应该已经更改。

从现在开始，旧令牌不再有效，并且不会向项目注册任何新的 runner。如果您使用任何工具来配置和注册新的 runner，则应更新这些工具中使用的令牌来反映新令牌的值。

确定 runner 的 IP 地址

了解 runner 的 IP 地址可能很有用，这样您就可以解决该 runner 的问题。极狐GitLab 在轮询作业时通过查看它向极狐GitLab 发出的 HTTP 请求的来源来存储和显示 IP 地址。IP 地址始终保持最新，因此如果 runner IP 更改，会在极狐GitLab 中自动更新。

共享 runner 和特定 runner 的 IP 地址可以在不同的地方找到。

确定共享 runner 的 IP 地址

要查看共享 runner 的 IP 地址，您必须具有极狐GitLab 实例的管理员访问权限：

在顶部栏上，选择 主菜单 > 管理员。
在左侧边栏，选择 概览 > Runners。
找到表中的 runner，查看 IP地址 栏。

确定特定 runner 的 IP 地址

要查找特定项目的 runner 的 IP 地址，您必须具有该项目的 Owner 角色。

转到项目的 设置 > CI/CD 并展开 Runners 部分。
在详细信息页面上，您应该会看到 IP 地址 一行。

使用标签来控制 runner 可以运行哪些作业

您必须设置一个 runner，以便能够运行它在共享的项目上可能遇到的所有不同类型的作业。如果不使用标签，这对于大量项目来说将是有问题的。

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

通过标记 runner 可以处理的作业类型，您可以确保共享 runner 将仅运行他们配备运行的作业。

例如，在极狐GitLab 中，如果 runner 包含运行 Rails 测试套件的适当依赖项，我们会使用 rails 标记 runner。

设置 runner 运行未标记的作业

当您注册一个 runner 时，它的默认行为是只选择已标记的作业。要更改此设置，您必须具有项目的所有者角色。

要让 runner 选择未标记的工作：

转到项目的 设置 > CI/CD 并展开 Runners 部分。
找到您要选择未标记工作的 runner 并确保它已启用。
单击铅笔按钮。
选中 运行未标记的作业 选项。
单击 保存修改 按钮使更改生效。

当不允许选择未标记的作业时，runner 标记列表不能为空。

下面是一些不同变化的示例场景。

Runner 只运行有标签作业

以下示例说明了将 runner 设置为仅运行有标签作业的潜在影响。

示例 1：

Runner 被配置为仅运行有标签的作业并具有 docker 标签。
一个带有 hello 标签的作业被执行并卡住。

示例 2：

Runner 被配置为仅运行有标签的作业并具有 docker 标签。
执行并运行具有 docker 标签的作业。

示例 3：

Runner 被配置为仅运行有标签的作业并具有 docker 标签。
未定义标签的作业被执行并卡住。

Runner 被允许运行未标记的作业

以下示例说明了将 runner 设置为运行有标签和未标记作业的潜在影响。

示例 1：

Runner 被配置为运行未标记的作业并具有 docker 标记。
执行并运行未定义标签的作业。
执行并运行定义了 docker 标签的第二个作业。

示例 2：

Runner 被配置为运行未标记的作业并且没有定义任何标记。
执行并运行未定义标签的作业。
定义了 docker 标签的第二个作业卡住了。

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

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

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

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

在标签中使用 CI/CD 变量

引入于 14.1 版本

您可以使用带有 tags 的 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_PATHS
GIT_SUBMODULE_UPDATE_FLAGS
GIT_DEPTH（浅克隆）
GIT_CLONE_PATH（自定义构建目录）
TRANSFER_METER_FREQUENCY（产物/缓存计量更新频率）
ARTIFACT_COMPRESSION_LEVEL（产物归档工具压缩级别）
CACHE_COMPRESSION_LEVEL（缓存归档工具压缩级别）
CACHE_REQUEST_TIMEOUT（缓存请求超时）

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

Git strategy

您可以在全局或每个作业 variables 部分中设置用于获取仓库内容的 GIT_STRATEGY：

variables:
  GIT_STRATEGY: clone

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

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

fetch 更快，因为它重新使用本地工作副本（如果它不存在则回退到 clone）。git clean 用于撤消上一个作业所做的任何更改，而 git fetch 用于检索上一个作业运行后所做的提交。

然而，fetch 确实需要访问前一个工作树。这在使用 shell 或 docker executor 时效果很好，因为它们会尝试保留工作树并尝试在默认情况下重用它们。

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

它可用于专门对产物进行操作的作业，例如部署作业。Git 仓库数据可能存在，但可能已过时。您应该只依赖从缓存或产物带入本地工作副本的文件。

Git submodule strategy

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

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

none 表示在获取项目代码时不包含子模块。这是默认值，与 v1.10 之前的行为相匹配。

normal 表示只包含顶级子模块。相当于：

git submodule sync
git submodule update --init

recursive 表示包含所有子模块（包括子模块的子模块）。此功能需要 Git v1.8.1 及更高版本。将 GitLab Runner 与不基于 Docker 的 executor 一起使用时，请确保 Git 版本满足该要求。相当于：
```
git submodule sync --recursive
git submodule update --init --recursive
```

要使此功能正常工作，必须使用以下任一方式配置子模块（在 .gitmodules 中）：

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

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

Git checkout

当 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 clean flags

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 fetch extra flags

引入于 GitLab Runner 13.1。

使用 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 的值。

Git submodule paths

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

此变量对于具有大量子模块的项目非常有用，并非所有子模块都需要在所有 CI 作业中同步或更新。

路径语法同 git submodule：

同步和更新特定路径：

 variables:
    GIT_SUBMODULE_PATHS: submoduleA submoduleB

要排除特定路径：

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

Git submodule update flags

引入于 GitLab Runner 14.8 版本

当 GIT_SUBMODULE_STRATEGY 设置为 normal 或 recursive 时，使用GIT_SUBMODULE_UPDATE_FLAGS 变量来控制 git submodule update 的行为。您可以在 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 而不是跟踪的提交，或者通过在多个并行作业中获取子模块来加速检出：

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 标志时，您应该注意对构建的安全性、稳定性和可重复性的影响。在大多数情况下，最好按照设计显式跟踪子模块提交，并使用自动修复/依赖机器人更新它们。

Shallow cloning

实验功能

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

在 12.0 及更高版本中，新创建的项目自动具有 git depth 值 50。

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

Git 获取和克隆基于 ref，例如分支名称，因此 runner 无法克隆特定的提交 SHA。如果队列中有多个作业，或者您正在重试旧作业，则要测试的提交必须在克隆的 Git 历史记录中。将 GIT_DEPTH 的值设置得太小会导致无法运行这些旧提交，并且在作业日志中会显示 unresolved reference。然后，您应该重新考虑将 GIT_DEPTH 更改为更高的值。

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

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

variables:
  GIT_DEPTH: "3"

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

Custom build directories

默认情况下，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 中设置的目录取决于 executor 和 runners.builds_dir 设置的配置。

只能在 runner 配置中启用 custom_build_dir 时使用。这是 docker 和 kubernetes executor 的默认配置。

Handling concurrency

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

Runner 不会试图阻止这种情况。是否符合 runner 配置的要求取决于管理员和开发人员。

为避免这种情况，您可以在 $CI_BUILDS_DIR 中使用唯一路径，因为 runner 公开了两个额外的变量，它们提供了唯一的并发 ID：

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

在任何场景和任何 executor 上都能正常工作的最稳定配置是在 GIT_CLONE_PATH 中使用 $CI_CONCURRENT_ID。例如：

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

test:
  script:
    - pwd

$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

Nested paths

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 没有展开而导致失败。

Job stages attempts

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

变量	描述
`ARTIFACT_DOWNLOAD_ATTEMPTS`	尝试下载运行作业的产物的次数
`EXECUTOR_JOB_SECTION_ATTEMPTS`	在 12.10 及更高版本中，在 `No Such Container` 错误（仅限 Docker executor）后尝试运行作业中的部分的次数。
`GET_SOURCES_ATTEMPTS`	尝试获取运行作业的源的次数
`RESTORE_CACHE_ATTEMPTS`	尝试恢复运行作业的缓存的次数

默认是一次尝试。

示例：

variables:
  GET_SOURCES_ATTEMPTS: 3

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

产物和缓存设置

引入于 GitLab Runner 13.9

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

在慢速网络上，对于较小的存档，上传速度可能会更快。
在不考虑带宽和存储的快速网络上，使用最快的压缩比上传可能会更快，尽管生成的存档更大。

可以启用 meter 来提供上传和下载的传输速率。

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

variables:
  # output upload and download progress every 2 seconds
  TRANSFER_METER_FREQUENCY: "2s"

  # Use fast compression for artifacts, resulting in larger archives
  ARTIFACT_COMPRESSION_LEVEL: "fast"

  # Use no compression for caches
  CACHE_COMPRESSION_LEVEL: "fastest"

  # Set maximum duration of cache upload and download
  CACHE_REQUEST_TIMEOUT: 5

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