Advanced configuration

要改变极狐GitLab Runner 和单个注册 runners 的行为，需要修改 config.toml 文件。

你可以在以下位置找到 config.toml 文件：

• 在 *nix 系统上，当极狐GitLab Runner 以 root 身份执行时，位于 /etc/gitlab-runner/。这个目录也是服务配置的路径。
• 在 *nix 系统上，当极狐GitLab Runner 以非 root 身份执行时，位于 ~/.gitlab-runner/。
• 在其他系统上，位于 ./。

极狐GitLab Runner 在更改大多数选项时不需要重启。这包括 [[runners]] 部分和全局部分的大多数参数，除了 listen_address。如果一个 runner 已经注册过，你不需要重新注册它。

极狐GitLab Runner 每 3 秒检查一次配置修改，并在必要时重新加载。极狐GitLab Runner 也会在接收到 SIGHUP 信号后重新加载配置。

配置验证#

配置验证是一个检查 config.toml 文件结构的过程。配置验证器的输出仅提供 info 级别的信息。

配置验证过程仅用于信息目的。您可以使用输出来识别 runner 配置中的潜在问题。配置验证可能无法捕捉所有可能的问题，且没有消息并不保证 config.toml 文件是完美无缺的。

全局部分#

这些设置是全局的。它们适用于所有 runners。

这是一个配置示例：

toml
1
2# 示例 `config.toml` 文件
3
4concurrent = 100 # 一个适用于此 `config.toml` 文件中定义的所有 runner 部分的作业并发性的全局设置
5log_level = "warning"
6log_format = "text"
7check_interval = 3 # 以秒为单位的值
8
9[[runners]]
10  name = "first"
11  url = "Your Gitlab instance URL (for example, `https://jihulab.com`)"
12  executor = "shell"
13  (...)
14
15[[runners]]
16  name = "second"
17  url = "Your Gitlab instance URL (for example, `https://jihulab.com`)"
18  executor = "docker"
19  (...)
20
21  [[runners]]
22  name = "third"
23  url = "Your Gitlab instance URL (for example, `https://jihulab.com`)"
24  executor = "docker-autoscaler"
25  (...)
26

log_format 示例（截断）#

runner#

shell
1Runtime platform                                    arch=amd64 os=darwin pid=37300 revision=HEAD version=development version
2Starting multi-runner from /etc/gitlab-runner/config.toml...  builds=0
3WARNING: Running in user-mode.
4WARNING: Use sudo for system-mode:
5WARNING: $ sudo gitlab-runner...
6
7Configuration loaded                                builds=0
8listen_address not defined, metrics & debug endpoints disabled  builds=0
9[session_server].listen_address not defined, session endpoints disabled  builds=0

text#

shell
1INFO[0000] Runtime platform                              arch=amd64 os=darwin pid=37773 revision=HEAD version="development version"
2INFO[0000] Starting multi-runner from /etc/gitlab-runner/config.toml...  builds=0
3WARN[0000] Running in user-mode.
4WARN[0000] Use sudo for system-mode:
5WARN[0000] $ sudo gitlab-runner...
6INFO[0000]
7INFO[0000] Configuration loaded                          builds=0
8INFO[0000] listen_address not defined, metrics & debug endpoints disabled  builds=0
9INFO[0000] [session_server].listen_address not defined, session endpoints disabled  builds=0

json#

shell
1{"arch":"amd64","level":"info","msg":"Runtime platform","os":"darwin","pid":38229,"revision":"HEAD","time":"2020-06-05T15:57:35+02:00","version":"development version"}
2{"builds":0,"level":"info","msg":"Starting multi-runner from /etc/gitlab-runner/config.toml...","time":"2020-06-05T15:57:35+02:00"}
3{"level":"warning","msg":"Running in user-mode.","time":"2020-06-05T15:57:35+02:00"}
4{"level":"warning","msg":"Use sudo for system-mode:","time":"2020-06-05T15:57:35+02:00"}
5{"level":"warning","msg":"$ sudo gitlab-runner...","time":"2020-06-05T15:57:35+02:00"}
6{"level":"info","msg":"","time":"2020-06-05T15:57:35+02:00"}
7{"builds":0,"level":"info","msg":"Configuration loaded","time":"2020-06-05T15:57:35+02:00"}
8{"builds":0,"level":"info","msg":"listen_address not defined, metrics \u0026 debug endpoints disabled","time":"2020-06-05T15:57:35+02:00"}
9{"builds":0,"level":"info","msg":"[session_server].listen_address not defined, session endpoints disabled","time":"2020-06-05T15:57:35+02:00"}

check_interval 的工作原理#

如果 config.toml 有多个 [[runners]] 部分，极狐GitLab Runner 包含一个不断调度作业请求到配置了极狐GitLab Runner 的极狐GitLab 实例的循环。

以下示例中，check_interval 为 10 秒，并有两个 [[runners]] 部分（runner-1 和 runner-2）。极狐GitLab Runner 每 10 秒发送一个请求，并休眠五秒：

1. 获取 check_interval 值（10s）。
2. 获取 runners 列表（runner-1，runner-2）。
3. 计算休眠间隔（10s / 2 = 5s）。
4. 开始一个无限循环：
   1. 请求 runner-1 的作业。
   2. 休眠 5s。
   3. 请求 runner-2 的作业。
   4. 休眠 5s。
   5. 重复。

这是一个 check_interval 配置示例：

toml
1# 示例 `config.toml` 文件
2
3concurrent = 100 # 一个适用于此 `config.toml` 文件中定义的所有 runner 部分的作业并发性的全局设置
4log_level = "warning"
5log_format = "json"
6check_interval = 10 # 以秒为单位的值
7
8[[runners]]
9  name = "runner-1"
10  url = "Your Gitlab instance URL (for example, `https://jihulab.com`)"
11  executor = "shell"
12  (...)
13
14[[runners]]
15  name = "runner-2"
16  url = "Your Gitlab instance URL (for example, `https://jihulab.com`)"
17  executor = "docker"
18  (...)

在此示例中，runner 进程每五秒发出一次作业请求。如果 runner-1 和 runner-2 连接到同一个极狐GitLab 实例，则该极狐GitLab 实例也每五秒收到来自此 runner 的新请求。

在 runner-1 的第一次和第二次请求之间发生两个休眠期。每个周期持续五秒，因此大约 10 秒之间的 runner-1 后续请求。对于 runner-2 也是如此。

如果定义更多 runners，则休眠间隔会更小。然而，在所有其他 runners 的请求及其休眠期被调用之后，runner 的请求才会重复。

[session_server] 部分#

要与作业交互，请在根级别（[[runners]] 部分之外）指定 [session_server] 部分。为所有 runners 配置此部分，而不是为每个单独的 runner 配置。

toml
1# 配置了 session server 的示例 `config.toml` 文件
2
3concurrent = 100 # 一个适用于此 `config.toml` 文件中定义的所有 runner 部分的作业并发性的全局设置
4log_level = "warning"
5log_format = "runner"
6check_interval = 3 # 以秒为单位的值
7
8[session_server]
9  listen_address = "[::]:8093" # 监听端口 `8093` 上所有可用接口
10  advertise_address = "runner-host-name.tld:8093"
11  session_timeout = 1800

配置 [session_server] 部分时：

• 对于 listen_address 和 advertise_address，使用格式 host:port，其中 host 是 IP 地址 (127.0.0.1:8093) 或域 (my-runner.example.com:8093)。runner 使用此信息创建一个 TLS 证书用于安全连接。
• 确保极狐GitLab 可以连接到 listen_address 或 advertise_address 中定义的 IP 地址和端口。
• 确保 advertise_address 是一个公共 IP 地址，除非您已启用应用程序设置 allow_local_requests_from_web_hooks_and_services。

要禁用 session server 和终端支持，请删除 [session_server] 部分。

如果您使用的是极狐GitLab Runner Docker 镜像，您必须通过在 docker run 命令 中添加 -p 8093:8093 来暴露端口 8093。

[[runners]] 部分#

每个 [[runners]] 部分定义一个 runner。

示例：

toml
1[[runners]]
2  name = "ruby-3.3-docker"
3  url = "https://CI/"
4  token = "TOKEN"
5  limit = 0
6  executor = "docker"
7  builds_dir = ""
8  shell = ""
9  environment = ["ENV=value", "LC_ALL=en_US.UTF-8"]
10  clone_url = "http://gitlab.example.local"

clone_url 的工作原理#

当极狐GitLab 实例位于 runner 无法使用的 URL 时，可以配置一个 clone_url。

例如，防火墙可能会阻止 runner 到达 URL。如果 runner 能够到达 192.168.1.23 上的节点，则将 clone_url 设置为 http://192.168.1.23。

如果设置了 clone_url，则 runner 构造一个 clone_url 形式的克隆 URL，例如 http://gitlab-ci-token:s3cr3tt0k3n@192.168.1.23/namespace/project.git。

修改 Git LFS 端点#

要修改 Git LFS 端点，请在以下文件之一中设置 pre_get_sources_script：

• config.toml：

  toml
  pre_get_sources_script = "mkdir -p $RUNNER_TEMP_PROJECT_DIR/git-template; git config -f $RUNNER_TEMP_PROJECT_DIR/git-template/config lfs.url https://<alternative-endpoint>"

• .gitlab-ci.yml：

  yaml
  default:
    hooks:
      pre_get_sources_script:
        - mkdir -p $RUNNER_TEMP_PROJECT_DIR/git-template
        - git config -f $RUNNER_TEMP_PROJECT_DIR/git-template/config lfs.url https://localhost

unhealthy_requests_limit 和 unhealthy_interval 的工作原理#

当极狐GitLab 实例长时间不可用时（例如，在版本升级期间），其 runners 变为闲置状态。在极狐GitLab 实例再次可用后，runners 在 30-60 分钟内不会恢复作业处理。

要增加或减少 runners 闲置的时间，请更改 unhealthy_interval 设置。

要更改 runner 连接到极狐GitLab 服务器的尝试次数并在接收到 unhealthy 请求后进入闲置状态，请更改 unhealthy_requests_limit 设置。有关更多信息，请参见 check_interval 的工作原理。

执行器#

以下是可用的执行器。

Shells#

当配置为使用 shell 执行器时，CI/CD 作业在主机机器上本地运行。支持的操作系统 shells 如下：

当 shell 选项设置为 bash 或 sh 时，Bash 的 ANSI-C quoting 用于 shell 转义作业脚本。

使用符合 POSIX 的 shell#

在极狐GitLab Runner 14.9 及更高版本中，启用功能标志 FF_POSIXLY_CORRECT_ESCAPES 以使用符合 POSIX 的 shell（如 dash）。启用后，将使用 "Double Quotes"，这是一种符合 POSIX 的 shell 转义机制。

[runners.docker] 部分#

以下设置定义了 Docker 容器参数。这些设置在 runner 配置为使用 Docker 执行器时适用。

Docker-in-Docker 作为服务，或任何在作业中配置的容器运行时，不会继承这些参数。

[[runners.docker.services]] 部分#

指定要与作业一起运行的其他服务。有关可用镜像的列表，请参阅 Docker Registry。 每个服务都在一个单独的容器中运行，并与作业链接。

示例：

toml
1[runners.docker]
2  host = ""
3  hostname = ""
4  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
5  image = "ruby:3.3"
6  memory = "128m"
7  memory_swap = "256m"
8  memory_reservation = "64m"
9  oom_kill_disable = false
10  cpuset_cpus = "0,1"
11  cpuset_mems = "0,1"
12  cpus = "2"
13  dns = ["8.8.8.8"]
14  dns_search = [""]
15  service_memory = "128m"
16  service_memory_swap = "256m"
17  service_memory_reservation = "64m"
18  service_cpuset_cpus = "0,1"
19  service_cpus = "2"
20  services_limit = 5
21  privileged = false
22  group_add = ["docker"]
23  cap_add = ["NET_ADMIN"]
24  cap_drop = ["DAC_OVERRIDE"]
25  devices = ["/dev/net/tun"]
26  disable_cache = false
27  wait_for_services_timeout = 30
28  cache_dir = ""
29  volumes = ["/data", "/home/project/cache"]
30  extra_hosts = ["other-host:127.0.0.1"]
31  shm_size = 300000
32  volumes_from = ["storage_container:ro"]
33  links = ["mysql_container:mysql"]
34  allowed_images = ["ruby:*", "python:*", "php:*"]
35  allowed_services = ["postgres:9", "redis:*", "mysql:*"]
36  [runners.docker.ulimit]
37    "rtprio" = "99"
38  [[runners.docker.services]]
39    name = "registry.example.com/svc1"
40    alias = "svc1"
41    entrypoint = ["entrypoint.sh"]
42    command = ["executable","param1","param2"]
43    environment = ["ENV1=value1", "ENV2=value2"]
44  [[runners.docker.services]]
45    name = "redis:2.8"
46    alias = "cache"
47  [[runners.docker.services]]
48    name = "postgres:9"
49    alias = "postgres-db"
50  [runners.docker.sysctls]
51    "net.ipv4.ip_forward" = "1"

[runners.docker] 部分中的卷#

有关卷的更多信息，请参阅 Docker 文档。

以下示例展示了如何在 [runners.docker] 部分中指定卷。

示例 1：添加数据卷#

数据卷是一个或多个容器中绕过联合文件系统的专门指定目录。数据卷旨在独立于容器的生命周期持久化数据。

toml
1[runners.docker]
2  host = ""
3  hostname = ""
4  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
5  image = "ruby:3.3"
6  privileged = false
7  disable_cache = true
8  volumes = ["/path/to/volume/in/container"]

此示例在容器中 /path/to/volume/in/container 处创建一个新卷。

示例 2：将主机目录挂载为数据卷#

当您希望将目录存储在容器之外时，可以将 Docker 守护进程的主机中的目录挂载到容器中：

toml
1[runners.docker]
2  host = ""
3  hostname = ""
4  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
5  image = "ruby:3.3"
6  privileged = false
7  disable_cache = true
8  volumes = ["/path/to/bind/from/host:/path/to/bind/in/container:rw"]

此示例在容器中的 /path/to/bind/in/container 使用 CI/CD 主机的 /path/to/bind/from/host。

极狐GitLab Runner 11.11 及更高版本 挂载主机目录 用于定义的服务 以及。

使用私有容器注册表#

要将私有注册表用作作业的镜像源，请使用 CI/CD 变量 DOCKER_AUTH_CONFIG 配置授权。您可以在以下之一中设置变量：

• 项目的 CI/CD 设置作为 file 类型
• config.toml 文件

使用 if-not-present 拉取策略的私有注册表可能会引入 安全隐患。 有关拉取策略如何工作的更多信息，请参阅 配置 runner 拉取镜像的方式。

有关使用私有容器注册表的更多信息，请参阅：

• 从私有容器注册表访问镜像
• .gitlab-ci.yml 关键字参考

runner 执行的步骤可以总结为：

1. 从镜像名称中找到注册表名称。
2. 如果值不为空，执行器会搜索此注册表的身份验证配置。
3. 最后，如果找到了与指定注册表相对应的身份验证，则后续拉取将使用它。

极狐GitLab 集成注册表的支持#

极狐GitLab 发送凭据用于其集成注册表与作业的数据一起。这些凭据会自动添加到注册表的授权参数列表中。

在此步骤之后，对注册表的授权过程类似于通过 DOCKER_AUTH_CONFIG 变量添加的配置。

在你的作业中，你可以使用任何来自极狐GitLab 集成注册表的镜像，即使镜像是私有的或受保护的。有关作业可以访问的镜像的信息，请阅读CI/CD 作业令牌文档文档。

Docker 授权解析的优先级#

如前所述，极狐GitLab Runner 可以通过使用不同方式发送的凭据来授权 Docker 访问注册表。为了找到合适的注册表，考虑以下优先级：

1. 使用 DOCKER_AUTH_CONFIG 配置的凭据。
2. 在极狐GitLab Runner 主机上本地配置的凭据，使用 ~/.docker/config.json 或 ~/.dockercfg 文件（例如，在主机上运行 docker login）。
3. 默认随作业负载发送的凭据（例如，前面描述的集成注册表的凭据）。

找到的第一个注册表凭据将被使用。例如，如果你通过 DOCKER_AUTH_CONFIG 变量为集成注册表添加了凭据，那么默认凭据将被覆盖。

runners.parallels 部分#

以下参数适用于 Parallels。

示例：

toml
[runners.parallels]
  base_name = "my-parallels-image"
  template_name = ""
  disable_snapshots = false

runners.virtualbox 部分#

以下参数适用于 VirtualBox。此执行器依赖于 vboxmanage 可执行文件来控制 VirtualBox 机器，因此你必须调整 Windows 主机上的 PATH 环境变量： PATH=%PATH%;C:\Program Files\Oracle\VirtualBox。

示例：

toml
[runners.virtualbox]
  base_name = "my-virtualbox-image"
  base_snapshot = "my-image-snapshot"
  disable_snapshots = false
  start_type = "headless"

start_type 参数决定了启动虚拟镜像时使用的图形前端。有效值为 headless（默认）、gui 或 separate，具体取决于主机和客户机组合的支持。

覆盖基础虚拟机镜像#

对于 Parallels 和 VirtualBox 执行器，你可以覆盖由 base_name 指定的基础虚拟机名称。为此，请在 .gitlab-ci.yml 文件中使用 image 参数。

为了向后兼容，默认情况下你不能覆盖此值。仅允许 base_name 指定的镜像。

为了允许用户通过 .gitlab-ci.yml 使用 image 参数选择虚拟机镜像：

toml
[runners.virtualbox]
  ...
  allowed_images = [".*"]

在此示例中，可以使用任何现有的虚拟机镜像。

allowed_images 参数是正则表达式的列表。配置可以根据需要精确。例如，如果你只想允许某些虚拟机镜像，可以使用如下正则表达式：

toml
[runners.virtualbox]
  ...
  allowed_images = ["^allowed_vm[1-2]$"]

在此示例中，只允许 allowed_vm1 和 allowed_vm2。任何其他尝试都会导致错误。

runners.ssh 部分#

以下参数定义 SSH 连接。

示例：

toml
1[runners.ssh]
2  host = "my-production-server"
3  port = "22"
4  user = "root"
5  password = "production-server-password"
6  identity_file = ""

runners.machine 部分#

以下参数定义基于 Docker Machine 的自动缩放功能。有关更多信息，请参阅 Docker Machine 执行器自动缩放配置。

[[runners.machine.autoscaling]] 部分#

以下参数定义在使用 Instance 或 Docker Autoscaler 执行器时可用的配置。

示例：

toml
1[runners.machine]
2  IdleCount = 5
3  IdleTime = 600
4  MaxBuilds = 100
5  MachineName = "auto-scale-%s"
6  MachineDriver = "google" # 参考 Docker Machine 文档了解如何认证：https://docs.docker.com/machine/drivers/gce/#credentials
7  MachineOptions = [
8      # 使用 Google Compute Engine 驱动程序可以添加额外的机器选项。
9      # 如果遇到主机不可达的问题（例如“等待 SSH”），
10      # 应该删除可选参数以帮助调试。
11      # https://docs.docker.com/machine/drivers/gce/
12      "google-project=GOOGLE-PROJECT-ID",
13      "google-zone=GOOGLE-ZONE", # 例如 'us-central1-a'，完整列表见 https://cloud.google.com/compute/docs/regions-zones/
14  ]
15  [[runners.machine.autoscaling]]
16    Periods = ["* * 9-17 * * mon-fri *"]
17    IdleCount = 50
18    IdleCountMin = 5
19    IdleScaleFactor = 1.5 # 表示当前空闲机器的数量将是 1.5*使用中的机器，
20                          # 不超过 50（IdleCount 的值），不少于 5（IdleCountMin 的值）
21    IdleTime = 3600
22    Timezone = "UTC"
23  [[runners.machine.autoscaling]]
24    Periods = ["* * * * * sat,sun *"]
25    IdleCount = 5
26    IdleTime = 60
27    Timezone = "UTC"

时间段语法#

Periods 设置包含以 cron 风格格式表示的时间段字符串的数组。该行包含以下字段：

plaintext
[second] [minute] [hour] [day of month] [month] [day of week] [year]

如同标准的 cron 配置文件，字段可以包含单个值、范围、列表和星号。查看语法的详细描述。

runners.instance 部分#

runners.autoscaler 部分#

以下参数配置自动缩放功能。你只能在 Instance 和 Docker Autoscaler 执行器中使用这些参数。

runners.autoscaler.plugin_config 部分#

此哈希表被重新编码为 JSON 并直接传递给配置的插件。

fleeting 插件通常会附带支持的配置的文档。

runners.autoscaler.scale_throttle 部分#

limit 和 burst 之间的关系#

缩放节流使用令牌配额系统来创建实例。此系统由两个值定义：

• burst：配额的最大大小。
• limit：每秒配额刷新率。

你可以一次创建的实例数量取决于剩余的配额。 如果你有足够的配额，你可以创建多达该数量的实例。 如果配额耗尽，你可以每秒创建 limit 个实例。 当实例创建停止时，配额每秒增加 limit，直到达到 burst 值。

例如，如果 limit 是 1 且 burst 是 60：

• 你可以立即创建 60 个实例，但会受到节流。
• 如果你等待 60 秒，可以立即创建另外 60 个实例。
• 如果不等待，你可以每秒创建 1 个实例。

runners.autoscaler.connector_config 部分#

fleeting 插件通常会附带支持的连接选项的文档。

插件会自动更新连接器配置。你可以使用 [runners.autoscaler.connector_config] 覆盖连接器配置的自动更新，或者填写插件无法确定的空值。

runners.autoscaler.state_storage 部分#

如果极狐GitLab Runner 在禁用状态存储（默认）时启动，为了安全起见，现有的 fleeting 实例会立即被移除。例如，当 max_use_count 设置为 1 时， 如果我们不知道其实例的使用状态，我们可能会不小心将作业分配给一个已使用的实例。

启用状态存储功能可以使实例的状态在本地磁盘上持久化。 在这种情况下，如果在极狐GitLab Runner 启动时存在实例，则不会被删除。其缓存的连接详细信息、使用计数和其他配置将被恢复。

启用状态存储功能时，请考虑以下信息：

• 实例的身份验证详细信息（用户名、密码、密钥） 将保留在磁盘上。

• 如果在极狐GitLab Runner 启动时实例正在积极运行作业，极狐GitLab Runner 默认会将其删除。此行为确保安全，因为极狐GitLab Runner 无法恢复作业。要保留实例，请将 keep_instance_with_acquisitions 设置为 true。

  将 keep_instance_with_acquisitions 设置为 true 有助于当你不关心实例上正在进行的作业时。你还可以使用 instance_ready_command 配置选项来清理环境以保留实例。这可能涉及停止所有正在执行的命令或强制删除 Docker 容器。

runners.autoscaler.policy 部分#

注意 - 在此上下文中，idle_count 指的是作业数量，而不是旧的自动缩放方法中的自动缩放机器数量。

为了决定是否移除空闲实例，taskscaler 将 idle_time 与实例的空闲持续时间进行比较。 每个实例的空闲周期是从实例：

• 上次完成作业（如果实例以前使用过）。
• 被预留时（如果从未使用过）。

此检查在缩放事件期间发生。超过配置的 idle_time 的实例将被移除，除非需要保持所需的 idle_count 作业容量。

当设置 scale_factor 时，idle_count 成为最小 idle 容量，而 scaler_factor_limit 是最大 idle 容量。

你可以定义多个策略。使用最后一个匹配的策略。

在以下示例中，空闲计数 1 在周一至周五的 08:00 到 15:59 之间使用。否则，空闲计数为 0。

toml
1[[runners.autoscaler.policy]]
2  idle_count        = 0
3  idle_time         = "0s"
4  periods           = ["* * * * *"]
5
6[[runners.autoscaler.policy]]
7  idle_count        = 1
8  idle_time         = "30m0s"
9  periods           = ["* 8-15 * * mon-fri"]

时间段语法#

periods 设置包含一个 UNIX-cron 格式化字符串的数组，用于表示策略启用的时间段。cron 格式由 5 个字段组成：

plaintext
1 ┌────────── 分钟 (0 - 59)
2 │ ┌──────── 小时 (0 - 23)
3 │ │ ┌────── 月中的日 (1 - 31)
4 │ │ │ ┌──── 月 (1 - 12)
5 │ │ │ │ ┌── 周中的日 (1 - 7 或 MON-SUN，0 是星期日的别名)
6 * * * * *

• - 可以用于两个数字之间以指定范围。
• * 可以用于表示该字段的有效值的整个范围。
• / 后跟一个数字或可以在范围后使用，以跳过该数字的范围。例如，小时字段的 0-12/2 将在 00:00 到 00:12 之间的每 2 小时激活一次。
• , 可以用于分隔字段的有效数字或范围的列表。例如，1,2,6-9。

值得注意的是，这个 cron 作业表示一个时间范围。例如：

runners.autoscaler.vm_isolation 部分#

虚拟机隔离使用 nesting，仅在 macOS 上支持。

runners.autoscaler.vm_isolation.connector_config 部分#

[runners.autoscaler.vm_isolation.connector_config] 部分的参数与 [runners.autoscaler.connector_config] 部分相同， 但用于连接到 nesting 预留的虚拟机，而不是自动缩放的实例。

runners.custom 部分#

以下参数定义了 自定义执行器 的配置。

runners.cache 部分#

以下参数定义了分布式缓存功能。详细信息请参阅 runner 自动缩放文档。

缓存机制使用预签名的 URL 上传和下载缓存。URL 由极狐GitLab Runner 在其自身实例上签署。 无论作业脚本（包括缓存上传/下载脚本）是在本地还是外部 机器上执行，这都无关紧要。例如，shell 或 docker 执行器在极狐GitLab Runner 进程运行的同一 机器上运行其脚本。同时，virtualbox 或 docker+machine 连接到单独的虚拟机以执行脚本。此过程是出于安全原因： 最大限度地减少泄露缓存适配器凭据的可能性。

如果 S3 缓存适配器 配置为使用 IAM 实例配置文件，则适配器使用附加到极狐GitLab Runner 机器的配置文件。 同样对于 GCS 缓存适配器，如果配置为 使用 CredentialsFile。该文件需要存在于极狐GitLab Runner 机器上。

下表列出了 config.toml、CLI 选项和 register 的环境变量。

runners.cache.s3 部分#

以下参数定义 S3 存储用于缓存。

示例：

toml
1[runners.cache]
2  Type = "s3"
3  Path = "path/to/prefix"
4  Shared = false
5  [runners.cache.s3]
6    ServerAddress = "s3.amazonaws.com"
7    AccessKey = "AWS_S3_ACCESS_KEY"
8    SecretKey = "AWS_S3_SECRET_KEY"
9    BucketName = "runners-cache"
10    BucketLocation = "eu-west-1"
11    Insecure = false
12    ServerSideEncryption = "KMS"
13    ServerSideEncryptionKeyID = "alias/my-key"

如果未指定 ServerAddress、AccessKey 或 SecretKey 并且未提供 AuthenticationType，那么 S3 客户端将使用 gitlab-runner 实例可用的 IAM 实例配置文件。在 autoscale 配置中，这不是执行作业的按需机器。如果 ServerAddress、AccessKey 和 SecretKey 都已指定，但未提供 AuthenticationType，则 access-key 用作身份验证类型。

当您使用 Helm charts 安装极狐GitLab Runner，并且在 values.yaml 文件中将 rbac.create 设置为 true 时，将创建一个 ServiceAccount。此 ServiceAccount 的注释从 rbac.serviceAccountAnnotations 部分中获取。

对于 Amazon EKS 上的 runners，您可以指定一个 IAM 角色来分配给服务账户。所需的具体注释是： eks.amazonaws.com/role-arn: arn:aws:iam::<ACCOUNT_ID>:role/<IAM_ROLE_NAME>。

此角色的 IAM 策略必须具有对指定桶执行以下操作的权限：

• s3:PutObject
• s3:GetObjectVersion
• s3:GetObject
• s3:DeleteObject

如果使用 KMS 类型的 ServerSideEncryption，则此角色还必须有权对指定的 AWS KMS 密钥执行以下操作：

• kms:Encrypt
• kms:Decrypt
• kms:ReEncrypt*
• kms:GenerateDataKey*
• kms:DescribeKey

不支持 SSE-C 类型的 ServerSideEncryption。SSE-C 要求除了预签名 URL 外，还提供包含用户提供密钥的标头以进行下载请求。这意味着需要将密钥材料传递给作业，而密钥无法保证安全。这确实有可能泄漏解密密钥。

在 S3 桶中为 runner 缓存使用 KMS 密钥加密#

GenerateDataKey API 使用 KMS 对称密钥为客户端加密创建数据密钥。KMS 密钥配置必须如下：

分配给 rbac.serviceAccountName 中定义的 ServiceAccount 的角色的 IAM 策略必须有权对 KMS 密钥执行以下操作：

• kms:GetPublicKey
• kms:Decrypt
• kms:Encrypt
• kms:DescribeKey
• kms:GenerateDataKey

使用 RoleARN 启用多部分传输#

为了限制对缓存的访问，runner 管理器为作业生成限时的预签名 URLs，用于从缓存下载和上传。然而，AWS S3 限制单个 PUT 请求到 5 GB。对于超过 5 GB 的文件，您必须使用多部分上传 API。

多部分传输仅支持 AWS S3，而不支持其他 S3 提供商。因为 runner 管理器处理不同项目的作业，所以它不能传递具有桶级权限的 S3 凭据。相反，runner 管理器使用限时的预签名 URLs 和范围狭窄的凭据来限制对特定对象的访问。

要在 AWS 上使用 S3 多部分传输，请在 RoleARN 中指定一个 IAM 角色，格式为 arn:aws:iam:::<ACCOUNT ID>:<YOUR ROLE NAME>。此角色生成限时的 AWS 凭据，这些凭据的范围仅限于写入桶中的特定 blob。确保您的原始 S3 凭据可以访问指定 RoleARN 的 AssumeRole。

在 RoleARN 中指定的 IAM 角色必须具有以下权限：

• 对 BucketName 中指定的桶的 s3:GetObject 访问。
• 对 BucketName 中指定的桶的 s3:PutObject 访问。
• 如果启用了带有 KMS 或 DSSE-KMS 的服务器端加密，则需要 kms:Decrypt 和 kms:GenerateDataKey。

例如，假设您有一个名为 my-instance-role 的 IAM 角色，附加到 ARN 为 arn:aws:iam::1234567890123:role/my-instance-role 的 EC2 实例。

您可以创建一个新角色 arn:aws:iam::1234567890123:role/my-upload-role，该角色仅对 BucketName 具有 s3:PutObject 权限。在 my-instance-role 的 AWS 设置中，Trust relationships 可能如下所示：

json
1{
2    "Version": "2012-10-17",
3    "Statement": [
4        {
5            "Effect": "Allow",
6            "Principal": {
7                "AWS": "arn:aws:iam::1234567890123:role/my-upload-role"
8            },
9            "Action": "sts:AssumeRole"
10        }
11    ]
12}

您还可以将 my-instance-role 重新用作 RoleARN，避免创建新角色。确保 my-instance-role 具有 AssumeRole 权限。例如，与 EC2 实例关联的 IAM 配置文件可能具有以下 Trust relationships：

json
1{
2    "Version": "2012-10-17",
3    "Statement": [
4        {
5            "Effect": "Allow",
6            "Principal": {
7                "Service": "ec2.amazonaws.com",
8                "AWS": "arn:aws:iam::1234567890123:role/my-instance-role"
9            },
10            "Action": "sts:AssumeRole"
11        }
12    ]
13}

您可以使用 AWS 命令行接口验证您的实例是否具有 AssumeRole 权限。例如：

shell
aws sts assume-role --role-arn arn:aws:iam::1234567890123:role/my-upload-role --role-session-name gitlab-runner-test1

使用 RoleARN 的上传工作原理#

如果存在 RoleARN，每次 runner 上传到缓存时：

1. runner 管理器检索原始 S3 凭据（通过 AuthenticationType、AccessKey 和 SecretKey 指定）。

2. 使用 S3 凭据，runner 管理器向 Amazon 安全令牌服务 (STS) 发送请求以获取 AssumeRole，带有 RoleARN。策略请求类似于以下内容：

   json
   1{
   2    "Version": "2012-10-17",
   3    "Statement": [
   4        {
   5            "Effect": "Allow",
   6            "Action": ["s3:PutObject"],
   7            "Resource": "arn:aws:s3:::<YOUR-BUCKET-NAME>/<CACHE-FILENAME>"
   8        }
   9    ]
   10}

3. 如果请求成功，runner 管理器将获得具有受限会话的临时 AWS 凭据。

4. runner 管理器将这些凭据和 URL 以 s3://<bucket name>/<filename> 格式传递给缓存归档器，然后缓存归档器上传文件。

为 Kubernetes ServiceAccount 资源启用 IAM 角色#

要为服务账户使用 IAM 角色，必须为您的集群存在一个 IAM OIDC 提供商。将 IAM OIDC 提供商与集群关联后，您可以创建一个 IAM 角色以与 runner 的服务账户关联。

1. 在 Create Role 窗口中，Select type of trusted entity 下，选择 Web Identity。

2. 在角色的 Trusted Relationships tab 上：

   • Trusted entities 部分必须具有以下格式： arn:aws:iam::<ACCOUNT_ID>:oidc-provider/oidc.eks.<AWS_REGION>.amazonaws.com/id/<OIDC_ID>。 OIDC ID 可以在 EKS 集群的 Configuration 标签上找到。

   • Condition 部分必须定义在 rbac.serviceAccountName 中定义的极狐GitLab Runner 服务账户或如果 rbac.create 设置为 true 时创建的默认服务账户：

     条件	键	值
     StringEquals	oidc.eks.<AWS_REGION>.amazonaws.com/id/<OIDC_ID>:sub	system:serviceaccount:<GITLAB_RUNNER_NAMESPACE>:<GITLAB_RUNNER_SERVICE_ACCOUNT>

使用 S3 Express One Zone 桶#

1. 按照 Amazon 教程设置 S3 Express One Zone 桶。
2. 使用 BucketName 和 BucketLocation 配置 config.toml。
3. 将 DualStack 设置为 false，因为 S3 Express 不支持双栈端点。

示例 config.toml：

toml
1[runners.cache]
2  Type = "s3"
3  [runners.cache.s3]
4    BucketName = "example-express--usw2-az1--x-s3"
5    BucketLocation = "us-west-2"
6    DualStack = false

[runners.cache.gcs] 部分#

示例：

直接在 config.toml 文件中配置的凭据：

toml
1[runners.cache]
2  Type = "gcs"
3  Path = "path/to/prefix"
4  Shared = false
5  [runners.cache.gcs]
6    AccessID = "cache-access-account@test-project-123456.iam.gserviceaccount.com"
7    PrivateKey = "-----BEGIN PRIVATE KEY-----\nXXXXXX\n-----END PRIVATE KEY-----\n"
8    BucketName = "runners-cache"

从 GCP 下载的 JSON 文件中的凭据：

toml
1[runners.cache]
2  Type = "gcs"
3  Path = "path/to/prefix"
4  Shared = false
5  [runners.cache.gcs]
6    CredentialsFile = "/etc/gitlab-runner/service-account.json"
7    BucketName = "runners-cache"

来自 GCP 中元数据服务器的应用程序默认凭据 (ADC)：

当您将极狐GitLab Runner 与 Google Cloud ADC 一起使用时，通常使用默认服务账户。然后您不需要为实例提供凭据：

toml
1[runners.cache]
2  Type = "gcs"
3  Path = "path/to/prefix"
4  Shared = false
5  [runners.cache.gcs]
6    BucketName = "runners-cache"

如果您使用 ADC，请确保您使用的服务账户具有 iam.serviceAccounts.signBlob 权限。

[runners.cache.azure] 部分#

以下参数定义了对 Azure Blob 存储的原生支持。虽然 S3 和 GCS 使用 bucket 一词来表示对象集合，但 Azure 使用 container 一词来表示 blob 的集合。

示例：

toml
1[runners.cache]
2  Type = "azure"
3  Path = "path/to/prefix"
4  Shared = false
5  [runners.cache.azure]
6    AccountName = "<AZURE STORAGE ACCOUNT NAME>"
7    AccountKey = "<AZURE STORAGE ACCOUNT KEY>"
8    ContainerName = "runners-cache"
9    StorageDomain = "blob.core.windows.net"

Azure 工作负载和托管身份#

要使用 Azure 工作负载或托管身份，请从配置中省略 AccountKey。当 AccountKey 为空时，runner 尝试：

1. 使用 DefaultAzureCredential 获取临时凭据。
2. 获取用户委派密钥。
3. 使用该密钥生成 SAS 令牌以访问存储账户 blob。

确保为实例分配了 Storage Blob Data Contributor 角色。如果实例无权执行上述操作，极狐GitLab Runner 会报告 AuthorizationPermissionMismatch 错误。

要使用 Azure 工作负载身份，请在 runner.kubernetes 部分中添加与身份关联的 service_account 和 pod 标签 azure.workload.identity/use。例如，如果 service_account 是 gitlab-runner：

toml
  [runners.kubernetes]
    service_account = "gitlab-runner"
    [runners.kubernetes.pod_labels]
      "azure.workload.identity/use" = "true"

确保 service_account 具有与其关联的 azure.workload.identity/client-id 注释：

yaml
serviceAccount:
  annotations:
    azure.workload.identity/client-id: <YOUR CLIENT ID HERE>

对于极狐GitLab 17.7 及更高版本，此配置足以设置工作负载身份。

然而，对于极狐GitLab Runner 17.5 和 17.6，您还必须使用以下内容配置 runner 管理器：

• azure.workload.identity/use pod 标签
• 要与工作负载身份一起使用的服务账户

例如，使用极狐GitLab Runner Helm chart：

yaml
serviceAccount:
  name: "gitlab-runner"
podLabels:
  azure.workload.identity/use: "true"

需要标签是因为凭据是从不同的来源检索的。对于缓存下载，凭据是从 runner 管理器中检索的。对于缓存上传，凭据是从运行 helper image 的 pod 中检索的。

[runners.kubernetes] 部分#

以下表格列出了 Kubernetes 执行器可用的配置参数。有关更多参数，请参阅 Kubernetes 执行器文档。

示例：

toml
1[runners.kubernetes]
2  host = "https://45.67.34.123:4892"
3  cert_file = "/etc/ssl/kubernetes/api.crt"
4  key_file = "/etc/ssl/kubernetes/api.key"
5  ca_file = "/etc/ssl/kubernetes/ca.crt"
6  image = "golang:1.8"
7  privileged = true
8  allow_privilege_escalation = true
9  image_pull_secrets = ["docker-registry-credentials", "optional-additional-credentials"]
10  allowed_images = ["ruby:*", "python:*", "php:*"]
11  allowed_services = ["postgres:9.4", "postgres:latest"]
12  logs_base_dir = "/tmp"
13  scripts_base_dir = "/tmp"
14  [runners.kubernetes.node_selector]
15    gitlab = "true"

辅助镜像#

当您使用 docker、docker+machine 或 kubernetes 执行器时，极狐GitLab Runner 使用一个特定的容器来处理 Git、产物和缓存操作。此容器是从名为 helper image 的镜像创建的。

辅助镜像适用于 amd64、arm、arm64、s390x 和 ppc64le 架构。它包含一个 gitlab-runner-helper 二进制文件，这是极狐GitLab Runner 二进制文件的特殊编译版本。它仅包含可用命令的子集，以及 Git、Git LFS 和 SSL 证书存储。

辅助镜像有几种风格：alpine、alpine3.18、alpine3.19、alpine3.21、alpine-latest、ubi-fips 和 ubuntu。由于其小巧的体积，alpine 镜像是默认的。使用 helper_image_flavor = "ubuntu" 选择 ubuntu 风格的辅助镜像。

在极狐GitLab Runner 16.1 到 17.1 中，alpine 风格是 alpine3.18 的别名。在极狐GitLab Runner 17.2 到 17.6 中，它是 alpine3.19 的别名。在极狐GitLab Runner 17.7 及更高版本中，它是 alpine3.21 的别名。

alpine-latest 风格使用 alpine:latest 作为其基础镜像，这可能意味着它更不稳定。

当极狐GitLab Runner 从 DEB 或 RPM 包中安装时，支持的架构的镜像会安装在主机上。如果 Docker Engine 找不到指定的镜像版本，runner 会在运行作业之前自动下载它。docker 和 docker+machine 执行器都以这种方式工作。

对于 alpine 风格，只有默认的 alpine 风格镜像包含在包中。所有其他风格均从注册表中下载。

kubernetes 执行器和极狐GitLab Runner 的手动安装工作方式不同。

• 对于手动安装，gitlab-runner-helper 二进制文件未包含。
• 对于 kubernetes 执行器，Kubernetes API 不允许从本地存档加载 gitlab-runner-helper 镜像。

在这两种情况下，极狐GitLab Runner 下载辅助镜像。极狐GitLab Runner 的修订版和架构定义了要下载的标签。

Kubernetes 上 Arm 的辅助镜像配置#

要在 arm64 Kubernetes 集群上使用 arm64 辅助镜像，请在您的 配置文件 中设置以下值。

toml
[runners.kubernetes]
        helper_image = "registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:arm64-latest"

使用旧版本 Alpine Linux 的 runner 镜像#

镜像是用多个版本的 Alpine Linux 构建的。您可以使用较新的 Alpine 版本，但同时也可以使用较旧的版本。

对于辅助镜像，改变 helper_image_flavor 或阅读 辅助镜像 部分。

对于极狐GitLab Runner 镜像，遵循相同的逻辑，其中 alpine、alpine3.18、alpine3.19、alpine3.21 或 alpine-latest 用作镜像的前缀，在版本之前：

shell
docker pull gitlab/gitlab-runner:alpine3.19-v16.1.0

Alpine pwsh 镜像#

从极狐GitLab Runner 16.1 及更高版本开始，所有 alpine 辅助镜像都有一个 pwsh 变体。唯一的例外是 alpine-latest，因为 powershell Docker 镜像基于的极狐GitLab Runner 辅助镜像不支持 alpine:latest。

示例：

shell
docker pull registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:alpine3.21-x86_64-v17.7.0-pwsh

辅助镜像注册表#

在极狐GitLab 15.0 及更早版本中，您可以配置辅助镜像以使用来自 Docker Hub 的镜像。

在极狐GitLab 15.1 及更高版本中，辅助镜像从极狐GitLab 容器注册表中拉取。

要从极狐GitLab 注册表检索基础 gitlab-runner-helper 镜像，请使用 helper-image 值：registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}。

极狐GitLab 私有化部署实例也会从 JihuLab.com 上的极狐GitLab 容器注册表中拉取辅助镜像。要检查极狐GitLab 容器注册表的状态，请参阅 极狐GitLab 系统状态。

覆盖辅助镜像#

在某些情况下，您可能需要覆盖辅助镜像，原因如下：

1. 加快作业执行速度：在网络连接较慢的环境中，多次下载同一镜像会增加执行作业所需的时间。从本地注册表下载辅助镜像，其中存储了 registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:XYZ 的准确副本，可以加快速度。

2. 安全问题：您可能不想下载未经过检查的外部依赖项。可能有一条业务规则，只使用已审核并存储在本地存储库中的依赖项。

3. 无网络访问的构建环境：如果您有 在脱机环境中安装的 Kubernetes 集群，您可以使用本地图像注册表或包存储库来拉取 CI/CD 作业中使用的图像。

4. 附加软件：您可能希望在辅助镜像中安装一些附加软件，例如 openssh，以支持使用 git+ssh 访问的子模块，而不是 git+http。

在这些情况下，您可以使用 helper_image 配置字段配置自定义镜像，该字段可用于 docker、docker+machine 和 kubernetes 执行器：

toml
1[[runners]]
2  (...)
3  executor = "docker"
4  [runners.docker]
5    (...)
6    helper_image = "my.registry.local/gitlab/gitlab-runner-helper:tag"

辅助镜像的版本应被认为是与极狐GitLab Runner 的版本严格耦合的。提供这些镜像的主要原因之一是极狐GitLab Runner 使用 gitlab-runner-helper 二进制文件。此二进制文件是从极狐GitLab Runner 源代码的一部分编译的。此二进制文件使用的内部 API 预计在两个二进制文件中是相同的。

默认情况下，极狐GitLab Runner 引用一个 registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:XYZ 镜像，其中 XYZ 基于极狐GitLab Runner 架构和 Git 修订版。在极狐GitLab Runner 11.3 及更高版本中，您可以使用 版本变量 之一定义镜像版本：

toml
1[[runners]]
2  (...)
3  executor = "docker"
4  [runners.docker]
5    (...)
6    helper_image = "my.registry.local/gitlab/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}"

通过此配置，极狐GitLab Runner 指示执行器使用版本为 x86_64-v${CI_RUNNER_VERSION} 的镜像，该版本基于其编译数据。在将极狐GitLab Runner 更新到新版本后，极狐GitLab Runner 会尝试下载适当的镜像。在升级极狐GitLab Runner 之前，应将镜像上传到注册表，否则作业将开始因 "No such image" 错误而失败。

在极狐GitLab Runner 13.2 及更高版本中，除了 $CI_RUNNER_REVISION 外，辅助镜像还以 $CI_RUNNER_VERSION 标记。这两个标签都是有效的，并指向同一个镜像。

toml
1[[runners]]
2  (...)
3  executor = "docker"
4  [runners.docker]
5    (...)
6    helper_image = "my.registry.local/gitlab/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}"

使用 PowerShell Core 时#

发布了一个适用于 Linux 的辅助镜像版本，其中包含 PowerShell Core，标记为 registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:XYZ-pwsh。

[runners.custom_build_dir] 部分#

此部分定义了 自定义构建目录 参数。

如果未明确配置此功能，则对于 kubernetes、docker、docker+machine、docker autoscaler 和 instance 执行器，此功能默认启用。对于所有其他执行器，默认情况下此功能禁用。

此功能要求 GIT_CLONE_PATH 位于 runners.builds_dir 中定义的路径中。要使用 builds_dir，请使用 $CI_BUILDS_DIR 变量。

默认情况下，此功能仅对 docker 和 kubernetes 执行器启用，因为它们提供了一种良好的资源分离方式。可以显式为任何执行器启用此功能，但在与共享 builds_dir 并且 concurrent > 1 的执行器一起使用时，请谨慎使用。

示例：

toml
[runners.custom_build_dir]
  enabled = true

默认构建目录#

极狐GitLab Runner 将存储库克隆到一个存在于更好称为 Builds Directory 的基本路径下的路径。此基本目录的默认位置取决于执行器。对于：

• Kubernetes、Docker 和 Docker Machine 执行器，它是在容器内的 /builds。
• 实例，它是在处理 SSH 或 WinRM 连接到目标机器的用户的主目录中的 ~/builds。
• Docker Autoscaler，它是在容器内的 /builds。
• Shell 执行器，它是 $PWD/builds。
• SSH、VirtualBox 和 Parallels 执行器，它是在处理 SSH 连接到目标机器的用户的主目录中的 ~/builds。
• 自定义 执行器，没有提供默认值，必须显式配置，否则作业失败。

用户可以通过 builds_dir 设置显式定义使用的 Builds Directory。

极狐GitLab Runner 使用 Builds Directory 运行它执行的所有作业，但使用特定模式 {builds_dir}/$RUNNER_TOKEN_KEY/$CONCURRENT_PROJECT_ID/$NAMESPACE/$PROJECT_NAME 嵌套它们。例如：/builds/2mn-ncv-/0/user/playground。

极狐GitLab Runner 不会阻止您在 Builds Directory 中存储内容。例如，您可以在 /builds/tools 中存储工具，以便在 CI 执行期间使用它们。我们 强烈 不建议这样做，您不应在 Builds Directory 中存储任何内容。极狐GitLab Runner 应该完全控制它，并且在这种情况下不提供稳定性。如果您的 CI 需要依赖项，您必须在其他地方安装它们。

清理 Git 配置#

在每次构建的开始和结束时，极狐GitLab Runner 会从存储库及其子模块中删除以下文件：

• Git 锁文件 ({index,shallow,HEAD,config}.lock)
• Post-checkout hooks (hooks/post-checkout)

如果您启用 clean_git_config，以下附加文件或目录将从存储库、其子模块和 Git 模板目录中删除：

• .git/config 文件
• .git/hooks 目录

此清理可防止在作业之间缓存自定义、临时或潜在的恶意 Git 配置。

在极狐GitLab Runner 17.10 之前，清理行为有所不同：

• Git 锁文件和 Post-checkout hooks 清理仅在作业开始时发生，而不是在作业结束时。
• 其他 Git 配置（现在由 clean_git_config 控制）除非设置 FF_ENABLE_JOB_CLEANUP，否则不会删除。当您设置此标志时，仅删除主存储库的 .git/config，而不是子模块配置。

clean_git_config 设置默认为 true。但在以下情况下默认为 false：

• 使用 Shell 执行器。
• Git 策略 设置为 none。

显式的 clean_git_config 配置优先于默认设置。

[runners.referees] 部分#

使用极狐GitLab Runner 裁判将额外的作业监控数据传递到极狐GitLab。裁判是 runner 管理器中的工作者，他们查询并收集与作业相关的其他数据。结果作为作业产物上传到极狐GitLab。

使用 Metrics Runner 裁判#

如果运行作业的机器或容器暴露 Prometheus 指标，极狐GitLab Runner 可以在整个作业期间查询 Prometheus 服务器。接收到指标后，它们作为作业产物上传，可以用于以后的分析。

只有 docker-machine 执行器 支持裁判。

为极狐GitLab Runner 配置 Metrics Runner 裁判#

在 [[runner]] 部分的 config.toml 文件中定义 [runner.referees] 和 [runner.referees.metrics]，并添加以下字段：

以下是 node_exporter 指标的完整配置示例：

toml
1[[runners]]
2  [runners.referees]
3    [runners.referees.metrics]
4      prometheus_address = "http://localhost:9090"
5      query_interval = 10
6      metric_queries = [
7        "arp_entries:rate(node_arp_entries{{selector}}[{interval}])",
8        "context_switches:rate(node_context_switches_total{{selector}}[{interval}])",
9        "cpu_seconds:rate(node_cpu_seconds_total{{selector}}[{interval}])",
10        "disk_read_bytes:rate(node_disk_read_bytes_total{{selector}}[{interval}])",
11        "disk_written_bytes:rate(node_disk_written_bytes_total{{selector}}[{interval}])",
12        "memory_bytes:rate(node_memory_MemTotal_bytes{{selector}}[{interval}])",
13        "memory_swap_bytes:rate(node_memory_SwapTotal_bytes{{selector}}[{interval}])",
14        "network_tcp_active_opens:rate(node_netstat_Tcp_ActiveOpens{{selector}}[{interval}])",
15        "network_tcp_passive_opens:rate(node_netstat_Tcp_PassiveOpens{{selector}}[{interval}])",
16        "network_receive_bytes:rate(node_network_receive_bytes_total{{selector}}[{interval}])",
17        "network_receive_drops:rate(node_network_receive_drop_total{{selector}}[{interval}])",
18        "network_receive_errors:rate(node_network_receive_errs_total{{selector}}[{interval}])",
19        "network_receive_packets:rate(node_network_receive_packets_total{{selector}}[{interval}])",
20        "network_transmit_bytes:rate(node_network_transmit_bytes_total{{selector}}[{interval}])",
21        "network_transmit_drops:rate(node_network_transmit_drop_total{{selector}}[{interval}])",
22        "network_transmit_errors:rate(node_network_transmit_errs_total{{selector}}[{interval}])",
23        "network_transmit_packets:rate(node_network_transmit_packets_total{{selector}}[{interval}])"
24      ]

指标查询采用 canonical_name:query_string 格式。查询字符串支持两个在执行期间被替换的变量：

例如，使用 docker-machine 执行器的共享极狐GitLab Runner 环境，其 {selector} 可能类似于 node=shared-runner-123。