高级配置

您可以改变极狐GitLab Runner 和单独注册的 Runner 的行为。

为此,您需要更改一个名为 config.toml 的文件,它使用 TOML 格式。

大多数选项的更改都不需要重启极狐GitLab Runner,包括 [[runners]] 部分的参数和全局部分的大多数参数,除了 listen_address。 如果已经注册了 Runner,您无需再次注册。

极狐GitLab Runner 每 3 秒查看一次配置更改,如有必要会重新加载配置。 极狐GitLab Runner 还会响应 SIGHUP 信号重新加载配置。

您可以在以下位置找到 config.toml 文件:

  • 当极狐GitLab Runner 以根用户执行(同样是服务配置的路径)时,*nix 系统上的 /etc/gitlab-runner/
  • 当极狐GitLab Runner 以非根用户执行时,*nix 系统上的 ~/.gitlab-runner/
  • 其他系统上的 ./

配置验证

引入于极狐GitLab Runner 15.10。

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

配置验证是尽力而为的,目前仅供参考。它可以帮助用户识别其 Runner 配置的潜在问题。它可能无法捕获所有可能的问题,并且没有任何消息并不能保证 config.toml 文件是完美无缺的。

随着时间的推移,验证过程将得到改进,以提供更准确、全面和有用的反馈。您应该使用最新版本的极狐GitLab Runner 以享受最新的改进和增强功能。

全局部分

以下是全局设置,适用所有 Runner。

设置 描述
concurrent 限制所有注册的 Runner 中并发运行的作业数量。每个 [[runners]] 部分可以定义它自己的限制,但是这个值为所有值的和设置了最大值。例如,10 表示不可以并发运行 10 个以上的作业。不可以使用 0,如果使用了这个值,Runner 进程会报严重错误。查看此设置如何与 Docker Machine 执行器相配合(弹性伸缩)
log_level 定义日志级别。选项包括 debuginfowarnerrorfatalpanic。 这个设置的级别比命令行参数 --debug-l--log-level 设置的级别低。
log_format 指定日志格式。选项包括 runnertextjson。这个设置比命令行参数 --log-format 设置的格式低。默认值为 runner,包含用于着色的 ANSI 转义码。
check_interval 定义 Runner 检查新作业的时间区间长度,单位为秒。默认值为 3。如果设置为 0 或更小的值,会使用默认值。
sentry_dsn 启动 Sentry 的所有系统级别的错误跟踪。
listen_address 定义 Prometheus 指标 HTTP 服务器应该侦听的地址(<host>:<port>)。
shutdown_timeout 强制关闭操作超时并退出进程之前的秒数。

配置示例:

concurrent = 4
log_level = "warning"

log_format 示例 (删节)

runner

Runtime platform                                    arch=amd64 os=darwin pid=37300 revision=HEAD version=development version
Starting multi-runner from /etc/gitlab-runner/config.toml...  builds=0
WARNING: Running in user-mode.
WARNING: Use sudo for system-mode:
WARNING: $ sudo gitlab-runner...

Configuration loaded                                builds=0
listen_address not defined, metrics & debug endpoints disabled  builds=0
[session_server].listen_address not defined, session endpoints disabled  builds=0

text

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

json

{"arch":"amd64","level":"info","msg":"Runtime platform","os":"darwin","pid":38229,"revision":"HEAD","time":"2020-06-05T15:57:35+02:00","version":"development version"}
{"builds":0,"level":"info","msg":"Starting multi-runner from /etc/gitlab-runner/config.toml...","time":"2020-06-05T15:57:35+02:00"}
{"level":"warning","msg":"Running in user-mode.","time":"2020-06-05T15:57:35+02:00"}
{"level":"warning","msg":"Use sudo for system-mode:","time":"2020-06-05T15:57:35+02:00"}
{"level":"warning","msg":"$ sudo gitlab-runner...","time":"2020-06-05T15:57:35+02:00"}
{"level":"info","msg":"","time":"2020-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"Configuration loaded","time":"2020-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"listen_address not defined, metrics \u0026 debug endpoints disabled","time":"2020-06-05T15:57:35+02:00"}
{"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 请求的间隔就会比您预期的更频繁。极狐GitLab Runner 包含一个不断向配置的极狐GitLab 实例调度请求的循环。

极狐GitLab Runner 试图保证以特定间隔向每个 Runner 发送后续请求。 为此,它用 [[runners]] 部分的数量除以 check_interval 的值。循环在所有部分中迭代,为每个部分调度请求,并在计算好的时间休眠。 当 Runner 和另一个极狐GitLab 实例绑定时会更加有趣。 请思考下面的例子。

如果您设置了 check_interval = 10,而且有两个 Runner (runner-1runner-2), 每 10 秒会发送一个请求。下面是这种情况中循环的一个例子:

  1. 获取 check_interval 值 (10s)。
  2. 获取 Runner 列表 (runner-1runner-2)。
  3. 计算休眠间隔 (10s / 2 = 5s)。
  4. 开启无限循环:
    1. runner-1 请求作业。
    2. 休眠 5s
    3. runner-2 请求作业。
    4. 休眠 5s
    5. 重复。

在这个例子中,Runner 进程每 5 秒发送一个请求。 如果 runner-1runner-2 连接到同一个极狐GitLab 实例,这个实例也会每 5 秒收到这个 Runner 发送的新请求。

runner-1 的第一个请求和 runner-1 的第二个请求之间,有两个休眠周期,每个 5 秒钟,所以 runner-1 的后续请求之间的间隔大约是 10 秒。 runner-2 也一样。

如果您定义了更多的 Runner,休眠间隔就会更小。然而,所有对其他 Runner 及其休眠周期的请求被调用后,会重复对 Runner 的请求。

[session_server] 部分

[session_server] 部分可以让用户和作业交互,例如在交互式 Web 终端中。

[session_server] 部分应该在根级别进行指定,而不是每个 Runner。 应该在 [[runners]] 部分之外对其进行定义。

[session_server]
  listen_address = "[::]:8093" #  listen on all available interfaces on port 8093
  advertise_address = "runner-host-name.tld:8093"
  session_timeout = 1800

配置 [session_server] 部分时:

  • 对于 listen_addressadvertise_address,使用 host:port 格式,其中 host 是 IP 地址 (127.0.0.1:8093) 或域 (my-runner.example.com:8093)。 Runner 使用此信息为安全连接创建 TLS 证书。
  • 确保您的网络浏览器可以连接到 advertise_address。实时会话由 Web 浏览器发起。
  • 确保 advertise_address 是公共 IP 地址,除非您启用了应用程序设置,allow_local_requests_from_web_hooks_and_services
设置 描述
listen_address 会话服务器的内部 URL。
advertise_address 访问会话服务器的 URL。极狐GitLab Runner 将其展现给极狐GitLab。如果未指定,则使用 listen_address
session_timeout 作业完成后,会话可以保持活跃的秒数。如果超时,作业就无法完成。默认为 1800 (30 分钟)。

如果想禁用会话服务器和终端支持,请删除 [session_server] 部分。

note 当您的 Runner 实例正在运行,您可能需要执行 gitlab-runner restart,使 [session_server] 部分中的变更生效。

如果您正在使用极狐GitLab Runner Docker 镜像,您必须添加 -p 8093:8093, 将端口 8093 显示给 docker run 命令

[[runners]] 部分

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

设置 描述
name Runner 的描述。仅供参考。
url 极狐GitLab 实例 URL。
token Runner 的认证令牌,在 Runner 注册过程中获取。
tls-ca-file 使用 HTTPS 时,包含验证对端的证书的文件。详情请参见自签名证书或自定义证书颁发机构(CA)文档
tls-cert-file 使用 HTTPS 时,包含认证对端的证书的文件。
tls-key-file 使用 HTTPS 时,包含认证对端的私钥的文件。
limit 限制注册 Runner 能够并发处理的作业数量。0 (默认)表示无限制。
executor 选择构建项目的方式。
shell 生成脚本的 Shell 的名称。默认值为依赖平台
builds_dir 在选择的执行器的上下文中存储构建的目录的绝对路径。例如:本地、Docker 或 SSH。
cache_dir 在选择的执行器的上下文中存储构建缓存的目录的绝对路径。例如:Docker 或 SSH。如果使用了 docker 执行器,该目录需要被包含到它的 volumes 参数中。
environment 附加或覆盖环境变量。
request_concurrency 极狐GitLab 的新作业的并发请求的限制数量,默认为 1
output_limit 最大构建日志大小(千字节),默认为 4096 (4MB)。
pre_clone_script 已废弃 - 现在使用 pre_get_sources_script
pre_get_sources_script 更新 Git 仓库和更新子模块前,Runner 上要执行的命令。例如,使用它来调整 Git 客户端配置。要插入多个命令,请使用(三引号)多行字符串或 \n 字符。
post_clone_script 已废弃 - 现在使用 post_get_sources_script
post_get_sources_script 更新 Git 仓库和更新子模块后,Runner 上要执行的命令。要插入多个命令,请使用(三引号)多行字符串或 \n 字符。
pre_build_script 执行构建前,Runner 上要执行的命令。如果要插入多个命令,使用(三引号)多行字符串或 \n 字符。
post_build_script 执行构建后且执行 after_script 前,Runner 上要执行的命令。如果要插入多个命令,使用(三引号)多行字符串或 \n 字符。
clone_url 覆盖极狐GitLab 实例的 URL。只有当 Runner 无法连接 GitLab URL 时使用。
debug_trace_disabled 禁用 CI_DEBUG_TRACE 功能。当设置成 true 时,调试日志(跟踪)一直禁用,即使 CI_DEBUG_TRACE 被用户设置为 true
referees 将结果向极狐GitLab 传递为作业产物的额外作业监控 worker。
unhealthy_requests_limit 对新工作请求的 unhealthy 响应次数,之后将禁用 Runner worker。
unhealthy_interval Runner worker 在超过不健康请求限制后被禁用的持续时间。支持 ‘3600s’ 或 ‘1h30min’ 等语法。

示例:

[[runners]]
  name = "ruby-2.7-docker"
  url = "https://CI/"
  token = "TOKEN"
  limit = 0
  executor = "docker"
  builds_dir = ""
  shell = ""
  environment = ["ENV=value", "LC_ALL=en_US.UTF-8"]
  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 会以 http://gitlab-ci-token:s3cr3tt0k3n@192.168.1.23/namespace/project.git 的形式创建克隆 URL。

执行器

以下执行器都可用。

执行器 所需配置 作业运行位置
shell   本地 Shell,默认执行器。
docker [runners.docker]Docker 引擎 Docker 容器。
docker-windows [runners.docker]Docker 引擎 Windows Docker 容器。
ssh [runners.ssh] SSH,远程。
parallels [runners.parallels][runners.ssh] 并行虚拟机,但与 SSH 相连。
virtualbox [runners.virtualbox][runners.ssh] VirtualBox 虚拟机,但与 SSH 相连。
docker+machine [runners.docker][runners.machine] 类似 docker,但使用弹性伸缩 Docker Machine
kubernetes [runners.kubernetes] Kubernetes pods。

Shell

可用的 Shell 可以在不同平台运行。

Shell 描述
bash 生成 Bash(Bourne-shell)脚本。所有在 Bash 上下文中执行的命令。是所有 Unix 系统的默认值。
sh 生成 Sh (Bourne-shell) 脚本。所有在 Sh 上下文中执行的命令。是所有 Unix 系统的应急计划。
powershell 生成 PowerShell 脚本。所有在 PowerShell Desktop 上下文中执行的命令。在极狐GitLab Runner 12.0-13.12 中,是 Windows 的默认值。
pwsh 生成 PowerShell 脚本。所有在 PowerShell Core 上下文中执行的命令。在极狐GitLab Runner 14.0 及更高版本中,是 Windows 的默认值。

shell 选项被设置为 bashsh 时,Bash 的 ANSI-C quoting 用于 Shell 转义作业脚本。

使用符合POSIX 的 Shell

在极狐GitLab Runner 14.9 及更高版本中,启用功能标志,标志名为 FF_POSIXLY_CORRECT_ESCAPES,以使用符合 POSIX 的 Shell(类似dash)。 启用后,会使用符合 POSIX 的 Shell 转移机制-“双引号”

[runners.docker] 部分

以下设置定义 Docker 容器参数。

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

参数 描述
allowed_images .gitlab-ci.yml 文件中可以指定的镜像的通配符列表。如果没有,则所有镜像都可以(等同于 ["*/*:*"])。和 DockerKubernetes 执行器一起使用。
allowed_privileged_images 当启用 privileged 时,在特权模式下运行的 allowed_images 的通配符子集。如果不存在,则允许所有镜像(相当于 ["*/*:*"])。与 Docker 执行器一起使用。
allowed_pull_policies 可以在 .gitlab-ci.yml 文件或 config.toml 文件中指定的拉取策略列表。如果未指定,则允许在 pull-policy 中指定的所有拉取策略。与 Docker 执行程序一起使用。
allowed_services .gitlab-ci.yml 文件中可以指定的服务的通配符列表。如果没有,则所有镜像都可以(等同于 ["*/*:*"])。和 DockerKubernetes 执行器一起使用。
allowed_privileged_services 当启用 privilegedservices_privileged 时,允许在特权模式下运行的 allowed_services 的通配符子集。如果不存在,则允许所有镜像(相当于 ["*/*:*"])。与 Docker 执行器一起使用。
cache_dir 应该存储 Docker 缓存的目录。可以是当前工作路径的绝对/相对路径。详情请参见 disable_cache
cap_add 向容器添加额外 Linux 能力。
cap_drop 从容器丢弃额外 Linux 能力。
cpuset_cpus 控制组的 CpusetCpus。字符串。
cpu_shares 用于设置相对 CPU 使用的 CPU share 的数量。默认为 1024
cpus CPU 的数量(Docker 1.13 和更高版本可用)。字符串。
devices 与容器共享额外主机设备。
device_cgroup_rules 自定义设备 cgroup 规则(Docker 1.28 及更高版本中可用)。
disable_cache Docker 执行器有两个级别的缓存:全局缓存(类似执行器)和基于 Docker 卷的本地缓存。这个配置标志仅在本地缓存中生效,本地缓存禁用了自动创建的(未映射到主机目录)缓存卷的使用。也就是说,如果 Runner 配置在分布式缓存模式中,它仅阻止创建存储构建临时文件的容器,并不禁用缓存。
disable_entrypoint_overwrite 禁用镜像入口点覆盖。
dns 要使用的容器的 DNS 服务器列表。
dns_search DNS 搜索域名列表。
extra_hosts 应该在容器环境中定义的主机。
gpus Docker 容器的 GPU 设备。与 docker 命令行界面使用同样的格式。详情请参见 Docker 文档
helper_image (高级)用于克隆目录并上传产物的默认 Helper 镜像。
helper_image_flavor 设置 Helper 镜像的类型 (alpinealpine3.15alpine3.16alpine3.17alpine3.18alpine-latestubi-fipsubuntu)。默认为 alpinealpinealpine3.18 使用一样的版本。
host 自定义 Docker 端点。默认为 DOCKER_HOST 环境或 unix:///var/run/docker.sock
hostname Docker 容器的自定义主机名。
image 运行作业的镜像。
links 与运行作业的容器相关联的容器。
memory 内存限制。字符串。
memory_swap 全部内存限制。字符串。
memory_reservation 内存软限制。字符串。
network_mode 向自定义网络添加容器。
mac_address 容器 MAC 地址(如 92:d0:c6:0a:29:33)。
oom_kill_disable 如果发生了内存溢出错误,不要在容器中结束进程。
oom_score_adjust 内存溢出得分调整。正数表明早些结束。
privileged 使容器在特权模式下运行。不安全。
services_privileged 允许服务在特权模式下运行。如果未设置(默认),则使用 privileged 值。与 Docker 执行器一起使用。不安全。
pull_policy 镜像拉取策略:neverif-not-presentalways(默认)。您可以在拉取策略文档中查看详细信息。您还可以添加多个拉取策略重试失败的拉取限制拉取策略
runtime Docker 容器的运行时。
isolation 容器隔离技术(defaulthypervprocess)。仅限 Windows 系统。
security_opt 安全选项(docker run 中的 security-opt)。取以 : 分隔的键/值的列表。
shm_size 镜像(单位为 byte)的共享内存的大小。
sysctls sysctl 选项。
tls_cert_path 存储和使用 ca.pemcert.pemkey.pem 与 Docker 建立安全 TLS 连接的目录。在 boot2docker 中很有用。
tls_verify 启用或禁用 Docker Daemon 连接的 TLS 验证。默认关闭。
user 以指定用户身份运行容器中的所有命令。
userns_mode 当启用了用户命名空间重新映射选项时,容器和 Docker 服务的用户命名空间模式。Docker 1.10 及更高版本中可用。
ulimit 传递给容器的 ulimit 值。使用与 Docker --ulimit 标志相同的语法。
volumes 应该挂载的额外的卷。Docker -v 标志的语法相同。
volumes_from 从另一个形式为 <container name>[:<ro |rw>] 的容器继承的卷列表。访问级别默认为读写,但是可以手动设置为 ro (只读)或 rw(读写)。
volume_driver 容器要使用的卷驱动。
wait_for_services_timeout 等待 Docker 服务的时间。设置成 -1 以禁用。默认为 30
container_labels 添加到 Runner 创建的每个容器的一组标记。标记值可以包括展开的环境变量。

[[runners.docker.services]] 部分

指定作业应该运行的额外服务。访问 Docker 镜像库 查看可用镜像列表。 服务在单独的容器中运行,并与作业相关联。

参数 描述
name 以服务运行的镜像的名称。
alias 可访问服务的额外的别名
entrypoint 应该被当作容器入口点执行的命令或脚本。语法类似于 Docker 文件的入口点 指令,其中每个 Shell 令牌都是阵列中单独的字符串。引入于极狐GitLab Runner 13.6。
command 应该被用作为容器命令的命令或脚本。语法类似于 Docker 文件的 CMD 指令,其中每个 Shell 令牌都是阵列中单独的字符串。引入于极狐GitLab Runner 13.6。
environment 附加或覆盖服务容器的环境变量。

示例:

[runners.docker]
host = ""
hostname = ""
tls_cert_path = "/Users/ayufan/.boot2docker/certs"
image = "ruby:2.7"
memory = "128m"
memory_swap = "256m"
memory_reservation = "64m"
oom_kill_disable = false
cpuset_cpus = "0,1"
cpus = "2"
dns = ["8.8.8.8"]
dns_search = [""]
privileged = false
userns_mode = "host"
cap_add = ["NET_ADMIN"]
cap_drop = ["DAC_OVERRIDE"]
devices = ["/dev/net/tun"]
disable_cache = false
wait_for_services_timeout = 30
cache_dir = ""
volumes = ["/data", "/home/project/cache"]
extra_hosts = ["other-host:127.0.0.1"]
shm_size = 300000
volumes_from = ["storage_container:ro"]
links = ["mysql_container:mysql"]
allowed_images = ["ruby:*", "python:*", "php:*"]
allowed_services = ["postgres:9", "redis:*", "mysql:*"]
[runners.docker.ulimit]
"rtprio" = "99"
[[runners.docker.services]]
name = "registry.example.com/svc1"
alias = "svc1"
entrypoint = ["entrypoint.sh"]
command = ["executable","param1","param2"]
environment = ["ENV1=value1", "ENV2=value2"]
[[runners.docker.services]]
name = "redis:2.8"
alias = "cache"
[[runners.docker.services]]
name = "postgres:9"
alias = "postgres-db"
[runners.docker.sysctls]
"net.ipv4.ip_forward" = "1"

[runners.docker] 部分中的卷

查看 Docker 卷使用的完全指南

以下例子展示如何指定 [runners.docker] 部分的卷。

示例 1:添加数据卷

数据卷是一个或多个绕过联合文件系统的容器中特殊指定的目录。数据卷不依赖容器的生命周期,持续存储数据。

[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:2.7"
  privileged = false
  disable_cache = true
  volumes = ["/path/to/volume/in/container"]

这个例子在 /path/to/volume/in/container 的容器中创建了一个新卷。

示例 2:以数据卷的形式挂载主机目录

当您想在容器外存储目录,您可以将目录从您的 Docker Daemon 的主机挂载到容器中:

[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:2.7"
  privileged = false
  disable_cache = true
  volumes = ["/path/to/bind/from/host:/path/to/bind/in/container:rw"]

这个例子使用了 /path/to/bind/in/container 中容器的 CI/CD 主机的 /path/to/bind/from/host

使用私有容器镜像库

如果您想把私有镜像库作为您作业镜像的来源,您可以在名为 DOCKER_AUTH_CONFIG 的 CI/CD 变量设置授权配置。 您还可以在项目的 CI/CD 中将变量设置为 File 类型或在 config.toml 文件中设置变量。

使用带有 if-not-present 拉取政策的私有镜像库可能会引入安全影响。 如果想充分理解拉取政策如何工作,请阅读拉取政策文档

详细示例请参见使用 Docker 镜像文档

Runner 进行的步骤可以归纳为:

  1. 从镜像名称中获取镜像库名称。
  2. 如果值不为空,执行器为镜像库搜索认证配置。
  3. 如果发现了与特定镜像库相匹配的认证,后续拉取会使用它。

现在 Runner 可以认证您的私有镜像库,访问如何配置 .gitlab-ci.yml 文件了解如何使用镜像库。

极狐GitLab 集成镜像库支持

极狐GitLab 发送作业数据时,也会发送它集成的镜像库的证书。 这些证书将自动添加到镜像库的认证参数列表中。

这步过后,对镜像库的认证会与添加 DOCKER_AUTH_CONFIG 参数的配置相似的方式继续。

在您的作业中,您可以使用您极狐GitLab 集成的镜像库中的任何镜像,即使镜像是私有的或受保护的。关于可以访问的镜像作业的信息,请参考 CI/CD 作业令牌文档

Docker 认证解析的优先级别

如前所述,极狐GitLab Runner 可以使用以不同方式发送的证书,通过比较镜像库来授权 Docker。 如果想要找到合适的镜像库,可以考虑以下优先级别:

  1. 使用 DOCKER_AUTH_CONFIG 配置的证书。
  2. 使用 ~/.docker/config.json~/.dockercfg 文件(例如在主机上运行 docker login)在极狐GitLab Runner 主机上本地配置的证书。
  3. 与作业负载一起默认发送的证书(例如之前描述的集成镜像库的证书)。

使用第一个发现的镜像库证书。例如,如果您使用 DOCKER_AUTH_CONFIG 变量为集成镜像库添加了证书,默认证书会被覆盖。

[runners.parallels] 部分

以下是 Parallels 的参数:

参数 描述
base_name 克隆的 Parallels VM 的名称。
template_name Parallels VM 关联模版的自定义名称。可选。
disable_snapshots 如果禁用,作业完成后会销毁虚拟机。
allowed_images 允许的 image/base_name 值的列表,以正则表达式的形式呈现。详情请参见覆盖基本虚拟机镜像部分。

示例:

[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

参数 解释
base_name 克隆的 VirtualBox VM 的名称。
base_snapshot 创建链接克隆的虚拟机的特定快照的名称或 UUID。如果这个值为空或省略,则使用当前快照。如果当前没有快照,会创建一个快照。除非 disable_snapshots 为 true,这种情况下,会进行基本虚拟机的完整克隆。
base_folder 保存新虚拟机的文件夹。如果这个值为空或省略,则使用默认虚拟机文件夹。
disable_snapshots 如果禁用,作业完成后会销毁虚拟机。
allowed_images 允许的 image/base_name 值的列表,以正则表达式的形式呈现。详情请参见覆盖基本虚拟机镜像部分。
start_type 启动 VM 时的图形前端类型。

示例:

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

start_type 参数确定启动虚拟镜像时使用的图形前端。主机和访客组合支持的有效值为 headless(默认)、guiseparate

覆盖基本虚拟机镜像

引入于极狐 GitLab Runner 14.2。

对于 Parallels 和 VirtualBox 执行器,您可以覆盖 base_name 指定的基本虚拟机的名称。 为此,您可以使用 .gitlab-ci.yml 文档中的镜像参数。

对于后向兼容,您无法默认覆盖这个值。仅允许 base_name 指定的镜像。

使用 .gitlab-ci.yml 镜像参数允许用户选择虚拟机镜像:

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

在这个例子中,可以使用任何现存的虚拟机镜像。

allowed_images 参数是正则表达式的列表。配置可以非常精确。 对于实例,如果您只想允许特定的虚拟机镜像,您可以使用正则表达式:

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

在这个例子中,仅允许了 allowed_vm1allowed_vm2。其他尝试都会带来错误。

[runners.ssh] 部分

以下参数定义 SSH 连接:

参数 描述
host 连接的地方。
port 端口。默认为 22
user 用户名
password 密码
identity_file SSH 私钥的文件地址(id_rsaid_dsaid_edcsa)。文件必须以非加密形式保存。
disable_strict_host_key_checking 在极狐GitLab 14.3 或更高版本中,这个值决定了 Runner 是否应该使用严格的主机密钥检查。默认为 true。在极狐GitLab 15.0 中,默认值为 false

示例:

[runners.ssh]
  host = "my-production-server"
  port = "22"
  user = "root"
  password = "production-server-password"
  identity_file = ""

[runners.machine] 部分

添加于极狐GitLab Runner v1.1.0。

以下参数定义基于 Docker Machine 的弹性伸缩功能。详情请参见 Runner 弹性伸缩文档

参数 描述
MaxGrowthRate 可以并行添加到 Runner 的机器的最大数量。默认值为 0 (无限制)。
IdleCount 需要创建且在闲置状态下等待的机器的数量。
IdleScaleFactor (实验性的)闲置机器的数量,该机器作为当前使用的机器的数量的一个因素。格式必须为浮点数。详情请参见弹性伸缩文档,默认为 0.0
IdleCountMin 当使用 IdleScaleFactor 时,需要创建且在闲置状态下等待的机器的最小数量。默认为 1。
IdleTime 机器在被移除前处于闲置状态的时间(秒)。
[[runners.machine.autoscaling]] 多个部分,每个部分都覆盖了弹性伸缩配置。最后一个包含匹配当前时间的表达式的部分被选中。
OffPeakPeriods 废弃:调度器在非峰值模式中的时长。cron-style 模式的阵列(如下文所述)。
OffPeakTimezone 废弃:OffPeakPeriods 中给定时间的时区。类似于 Europe/Berlin 的时区串。若为空或省略,默认为主机的本地系统设置。极狐GitLab Runner 试图在目录中或 ZONEINFO 环境变量命名的未压缩的文件中定位时区数据库,然后在 Unix 系统中查找已知安装位置,最终在 $GOROOT/lib/time/zoneinfo.zip 中查找。
OffPeakIdleCount 废弃:类似于 IdleCount,但是对于 Off Peak 时长。
OffPeakIdleTime 废弃:类似于 IdleTime,但是对于 Off Peak 时长。
MaxBuilds 机器移除前,最大作业(构建)的数量。
MachineName 机器的名称。必须包含 %s,用唯一机器标识符替代。
MachineDriver Docker Machine driver。详情请参见Docker Machine 配置部分
MachineOptions Docker Machine 选项。详情请参见Docker Machine 配置部分

[[runners.machine.autoscaling]] 部分

参数 描述
Periods 调度活跃的时间间隔。cron-style 模式的阵列(如下文所述)。
IdleCount 需要创建且在闲置状态下等待的机器的数量。
IdleScaleFactor (实验性的)闲置机器的数量,该机器作为当前使用的机器的数量的一个因素。格式必须为浮点数。详情请参见弹性伸缩文档。默认为 0.0
IdleCountMin 当使用 IdleScaleFactor 时,需要创建且在闲置状态下等待的机器的最小数量。默认为 1。
IdleTime 机器在被移除前处于闲置状态的时间(秒)。
Timezone Periods 中给定时间的时区。类似于 Europe/Berlin 的时区串。若为空或省略,默认为主机的本地系统设置。极狐GitLab Runner 试图在目录中或 ZONEINFO 环境变量命名的未压缩的文件中定位时区数据库,然后在 Unix 系统中查找已知安装位置,最终在 $GOROOT/lib/time/zoneinfo.zip 中查找。

示例:

[runners.machine]
  IdleCount = 5
  IdleTime = 600
  MaxBuilds = 100
  MachineName = "auto-scale-%s"
  MachineDriver = "google" # Refer to Docker Machine docs on how to authenticate: https://docs.docker.com/machine/drivers/gce/#credentials
  MachineOptions = [
      # Additional machine options can be added using the Google Compute Engine driver.
      # If you experience problems with an unreachable host (ex. "Waiting for SSH"),
      # you should remove optional parameters to help with debugging.
      # https://docs.docker.com/machine/drivers/gce/
      "google-project=GOOGLE-PROJECT-ID",
      "google-zone=GOOGLE-ZONE", # e.g. 'us-central1-a', full list in https://cloud.google.com/compute/docs/regions-zones/
  ]
  [[runners.machine.autoscaling]]
    Periods = ["* * 9-17 * * mon-fri *"]
    IdleCount = 50
    IdleCountMin = 5
    IdleScaleFactor = 1.5 # Means that current number of Idle machines will be 1.5*in-use machines,
                          # no more than 50 (the value of IdleCount) and no less than 5 (the value of IdleCountMin) 
    IdleTime = 3600
    Timezone = "UTC"
  [[runners.machine.autoscaling]]
    Periods = ["* * * * * sat,sun *"]
    IdleCount = 5
    IdleTime = 60
    Timezone = "UTC"

Periods 语法

Periods 设置包括格式为 cron-style 的时长的字符串模式的阵列。行包括以下字段:

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

类似于标准的 cron 配置文件,字段可以包括单个值、范围、列表和星号。详情请参见语法详细描述

[runners.instance] 部分(Alpha)

以下参数定义实力执行器的配置。

参数 类型 描述
allowed_images string 当启用了 VM 隔离,allowed_images 控制作业允许指定的镜像

[runners.autoscaler] 部分

添加于极狐GitLab Runner v15.10.0。

以下参数配置新的和实验性的弹性伸缩器功能,只能与实例Docker Autoscaler 执行器一起使用。

参数 说明
capacity_per_instance 单个实例可以并发执行的作业数
max_use_count 实例在计划删除之前可以使用的最大次数
max_instances 允许的最大实例数,这与实例状态(挂起、运行、删除)无关。默认值:0(无限制)
plugin 要使用的 fleeting 插件。二进制文件必须可通过 PATH 环境变量发现

[runners.autoscaler.plugin_config] 部分

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

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

[runners.autoscaler.connector_config] 部分

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

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

参数 说明
os 实例的操作系统
arch 实例的架构
protocol 要使用的协议:sshwinrm
username 用于连接的用户名
password 用于连接的密码
key_pathname 用于连接或动态提供证书的 TLS key
use_static_credentials 禁用自动证书配置。默认值:false
keepalive 连接保活持续时间
timeout 连接超时时间
use_external_addr 是否使用插件提供的外部地址。如果插件仅返回内部地址,则无论此设置如何都将使用它。默认值:false

[[runners.autoscaler.policy]] 部分

Note - 本上下文中的 idle_count 指的是作业数量,而不是传统弹性伸缩方法中弹性伸缩机器的数量。

periods 一组 unix-cron 格式的字符串,用于表示启用此策略的时间段。默认值:* * * * *
timezone 评估 unix-cron 周期时使用的时区。默认值:系统的本地时区
idle_count 我们希望立即可用于作业的目标空闲容量
idle_time 实例在终止之前可以空闲的时间量
scale_factor 我们希望在 idle_count 之上立即可用于作业的目标闲置容量,作为当前使用容量的一个因素。默认为 0.0
scale_factor_limit scale_factor 计算可以产生的最大容量

设置 scale_factor 后,idle_count成为最小 idle 容量,scaler_factor_limit 成为最大 idle 容量。

Periods 语法

periods 设置包含一组 unix-cron 格式的字符串,用于表示策略启用的时间段。这个 cron 格式包含 5 个字段:

 ┌────────── minute (0 - 59)
 │ ┌──────── hour (0 - 23)
 │ │ ┌────── day of month (1 - 31)
 │ │ │ ┌──── month (1 - 12)
 │ │ │ │ ┌── day of week (1 - 7 or MON-SUN, 0 is an alias for Sunday)
 * * * * *
  • 可以在两个数字之间使用 - 来指定范围。
  • * 可用于表示该字段的整个有效值范围。
  • / 后跟一个数字,或者可以在范围之后使用以跳过该范围内的数字。例如,小时字段的 0-12/2 将在 00:00 和 00:12 之间每 2 小时激活一次周期。
  • , 可用于分隔字段的有效数字或范围列表。例如,1,2,6-9

值得记住的是,这个 cron 作业代表一个时间范围。例如:

周期 影响
1 * * * * * 每小时启用 1 分钟的规则(不太可能非常有用)
* 0-12 * * * 在每天的前 12 小时启用的规则
0-30 13,16 * * SUN 在每个星期日下午 1 点 启用 30 分钟和下午 4 点启用 30 分钟的规则

[runners.custom] 部分

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

参数 类型 描述
config_exec 字符串 可执行文件的路径,所以用户可以在作业开始前覆盖一些配置设置。这些值覆盖了[[runners]] 部分中设置的值。自定义执行器文档中有完整列表。
config_args 字符串阵列 传递到 config_exec 可执行文件中的第一组参数。
config_exec_timeout 整数 config_exec 完成执行的超时时间(秒)。默认为 3600 秒(1 小时)。
prepare_exec 字符串 准备环境的可执行文件的路径。
prepare_args 字符串阵列 传递到 prepare_exec 可执行文件的第一组参数。
prepare_exec_timeout 整数 prepare_exec 完成执行的超时时间(秒)。默认为 3600 秒(1 小时)。
run_exec 字符串 必选。在环境中运行脚本的可执行文件的路径。例如,克隆和构建脚本。
run_args 字符串阵列 传递到 run_exec 可执行文件的第一组参数。
cleanup_exec 字符串 清理环境的可执行文件的路径。
cleanup_args 字符串阵列 传递到 cleanup_exec 可执行文件的第一组参数。
cleanup_exec_timeout 整数 cleanup_exec 完成执行的超时时间(秒)。默认为 3600 秒(1 小时)。
graceful_kill_timeout 整数 prepare_execcleanup_exec 终止(例如作业取消)时,它们的等待时间(秒)。这个超时时间过后,进程结束。默认为 600 秒(10 分钟)。
force_kill_timeout 整数 将关闭信号发送到脚本之后的等待时间(秒)。默认为 600 秒(10 分钟)。

[runners.cache] 部分

引入于极狐GitLab Runner 1.1.0。

以下参数定义了分布式缓存功能。在 Runner 弹性伸缩文档中查看详情。

参数 类型 描述
Type 字符串 s3gcsazure 中之一。
Path 字符串 在缓存 URL 前面添加的路径的名称。
Shared 布尔 在 Runner 间开启缓存共享。默认为 false
MaxUploadedArchiveSize int64 上传到云存储的缓存存档的限制(以字节为单位)。恶意行为者可以绕过此限制,因此 GCS 适配器会通过签名 URL 中的 X-Goog-Content-Length-Range 标头强制执行此限制。您还应该对您的云存储提供商设置限制。
caution 在极狐GitLab Runner 11.3 中,S3 相关的配置参数被移动到了特定的 [runners.cache.s3] 部分。 S3 直接配置在 [runners.cache] 已经被废弃。 在极狐GitLab Runner 12.0 中,移除了配置语法,且后面不会再支持

缓存机制使用预签名 URL 上传和下载缓存。极狐GitLab Runner 在它的实例上进行 URL 签名。 作业脚本(包括缓存上传/下载脚本)无论在本地或外部机器上执行都可以。例如 shelldocker 执行器在同一个运行极狐GitLab Runner 程序的机器上运行脚本。同时,virtualboxdocker+machine 连接到单独的虚拟机,以执行脚本。这个过程是为了安全考虑:将泄漏缓存适配器证书的可能性降到最低。

如果 S3 缓存适配器被配置为使用 IAM 实例配置文件,适配器会使用附着到极狐GitLab Runner 机器的配置文件。 如果被配置为使用 CredentialsFile ,则类似于 GCS 缓存适配器。文件需要在极狐GitLab Runner 机器上。

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

设置 TOML 字段 register 的 CLI 选项 register 的 ENV
Type [runners.cache] -> Type --cache-type $CACHE_TYPE
Path [runners.cache] -> Path --cache-path

12.0 之前,--cache-s3-cache-path
$CACHE_PATH

12.0 之前,$S3_CACHE_PATH
Shared [runners.cache] -> Shared --cache-shared

12.0 之前,--cache-s3-cache-path
$CACHE_SHARED
S3.ServerAddress [runners.cache.s3] -> ServerAddress --cache-s3-server-address $CACHE_S3_SERVER_ADDRESS

12.0 之前,$S3_SERVER_ADDRESS
S3.AccessKey [runners.cache.s3] -> AccessKey --cache-s3-access-key $CACHE_S3_ACCESS_KEY

12.0 之前,$S3_ACCESS_KEY
S3.SecretKey [runners.cache.s3] -> SecretKey --cache-s3-secret-key $CACHE_S3_SECRET_KEY

12.0 之前,$S3_SECRET_KEY
S3.BucketName [runners.cache.s3] -> BucketName --cache-s3-bucket-name $CACHE_S3_BUCKET_NAME

12.0 之前,$S3_BUCKET_NAME
S3.BucketLocation [runners.cache.s3] -> BucketLocation --cache-s3-bucket-location $CACHE_S3_BUCKET_LOCATION

12.0 之前,$S3_BUCKET_LOCATION
S3.Insecure [runners.cache.s3] -> Insecure --cache-s3-insecure $CACHE_S3_INSECURE

12.0 之前,$S3_INSECURE
S3.AuthenticationType [runners.cache.s3] -> AuthenticationType --cache-s3-authentication_type $CACHE_S3_AUTHENTICATION_TYPE
GCS.AccessID [runners.cache.gcs] -> AccessID --cache-gcs-access-id $CACHE_GCS_ACCESS_ID
GCS.PrivateKey [runners.cache.gcs] -> PrivateKey --cache-gcs-private-key $CACHE_GCS_PRIVATE_KEY
GCS.CredentialsFile [runners.cache.gcs] -> CredentialsFile --cache-gcs-credentials-file $GOOGLE_APPLICATION_CREDENTIALS
GCS.BucketName [runners.cache.gcs] -> BucketName --cache-gcs-bucket-name $CACHE_GCS_BUCKET_NAME
Azure.AccountName [runners.cache.azure] -> AccountName --cache-azure-account-name $CACHE_AZURE_ACCOUNT_NAME
Azure.AccountKey [runners.cache.azure] -> AccountKey --cache-azure-account-key $CACHE_AZURE_ACCOUNT_KEY
Azure.ContainerName [runners.cache.azure] -> ContainerName --cache-azure-container-name $CACHE_AZURE_CONTAINER_NAME
Azure.StorageDomain [runners.cache.azure] -> StorageDomain --cache-azure-storage-domain $CACHE_AZURE_STORAGE_DOMAIN

[runners.cache.s3] 部分

以下参数定义了缓存的 S3 存储。

在极狐GitLab Runner 11.2 及更低版本中,这些设置在全局 [runners.cache] 部分中。

参数 类型 描述
ServerAddress 字符串 兼容 S3 的服务器的 host:port。如果您使用的是 AWS 之外的其他服务器,请参考存储产品文件,以决定正确地址。对于 DigitalOcean,地址的格式必须为 spacename.region.digitaloceanspaces.com
AccessKey 字符串 为您的 S3 实例指定的访问密钥。
SecretKey 字符串 为您的 S3 实例指定的密钥。
BucketName 字符串 存储缓存的存储桶的名称。
BucketLocation 字符串 S3 区域的名称。
Insecure 布尔 如果 S3 服务通过 HTTP 可用,设置为 true。默认为 false
AuthenticationType 字符串 在极狐GitLab 14.4 及更高版本中,设置为 iamaccess-key。如果提供了 ServerAddressAccessKeySecretKey,则默认为 access-key;如果 ServerAddressAccessKeySecretKey 缺失,默认为 iam
ServerSideEncryption 字符串 在极狐GitLab 15.3 及更高版本中,和 S3 可用类型一起使用的服务器端加密类型为 S3KMS
ServerSideEncryptionKeyID 字符串 在极狐GitLab 15.3 及更高版本中,如果使用 KMS,是用于加密的 KMS key 的别名或 ID。

示例:

[runners.cache]
  Type = "s3"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.s3]
    ServerAddress = "s3.amazonaws.com"
    AccessKey = "AWS_S3_ACCESS_KEY"
    SecretKey = "AWS_S3_SECRET_KEY"
    BucketName = "runners-cache"
    BucketLocation = "eu-west-1"
    Insecure = false
    ServerSideEncryption = "KMS"
    ServerSideEncryptionKeyID = "alias/my-key"

如果未指定 ServerAddressAccessKeySecretKey 且未提供 AuthenticationType,S3 客户端会使用 gitlab-runner 实例可用的 IAM 实例配置文件。在弹性伸缩配置中,这不是执行作业的按需机器。 如果指定了 ServerAddressAccessKeySecretKey,但未提供 AuthenticationTypeaccess-key 会被用作认证类型。

当您使用 Helm Chart 安装极狐GitLab Runner,且在 values.yaml 文件中将rbac.create 设置为 true, 就会创建 ServiceAccount。ServiceAccount 的注释从 rbac.serviceAccountAnnotations 部分进行检索。

对于 Amazon EKS 上的 Runner,您可以指定分配给服务账户的 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 类型的 ServerSideEncryptionSSE-C 要求除了预签名的 URL 之外,还为下载请求提供包含用户提供的密钥的 header。 这意味着将密钥材料传递给无法保证密钥安全的作业。这确实有可能泄漏解密密钥。

note 可被上传至 AWS S3 缓存的单个文件最大为 5 GB。

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

GenerateDataKey API 使用 KMS 对称密钥为客户端加密((https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html))创建数据密钥。KMS 密钥配置需要:

属性 描述
Key Type 对称
Origin AWS_KMS
Key Spec SYMMETRIC_DEFAULT
Key Usage 加密和解密

分配到 rbac.serviceAccountName 中定义的 ServiceAccount 的角色的 IAM 政策需要能够为 KMS 密钥做下列动作:

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

为 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>。 可以在 EKS 集群的 Configuration 选项卡中找到 OIDC ID

    • 如果 rbac.create 设置为 trueCondition 部分必须拥有 rbac.serviceAccountName 中定义的极狐GitLab Runner 服务账户或创建的默认服务账户:

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

[runners.cache.gcs] 部分

引入于极狐GitLab Runner 11.3.0。

以下参数定义了谷歌云存储(GCS)的原生支持。值的来源请查看谷歌云存储认证文档

参数 类型 描述
CredentialsFile 字符串 谷歌 JSON 密钥文件的路径。仅支持 service_account 类型,如果进行了配置,这个值的优先级高于直接配置在 config.toml 中的 AccessIDPrivateKey
AccessID 字符串 用于访问存储的 GCP 服务账户的 ID。
PrivateKey 字符串 进行 GCS 请求签名的私钥。
BucketName 字符串 存储缓存的存储桶的名称。

示例:

证书直接配置在 config.toml 文件中:

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

从 GCP 下载的 JSON 文件中的证书:

[runners.cache]
  Type = "gcs"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.gcs]
    CredentialsFile = "/etc/gitlab-runner/service-account.json"
    BucketName = "runners-cache"

GCP 中元数据服务器的应用程序默认证书 (ADC):

当您通过 Google Cloud ADC 使用极狐GitLab Runner 时,您通常使用默认服务账户。您不需要为实例提供证书:

[runners.cache]
  Type = "gcs"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.gcs]
    BucketName = "runners-cache"

如果您使用 ADC,请确保您使用的服务账户拥有 iam.serviceAccounts.signBlob 权限。通常,这是通过将服务账户令牌创建者角色授予服务账户来完成的。

[runners.cache.azure] 部分

引入于极狐GitLab Runner 13.4.0。

以下参数定义 Azure Blob Storage 的原生支持。详情请参见 Azure Blob Storage 文档。 S3 和 GCS 为许多对象使用词语 bucket,Azure 使用词语 container 表示许多 blobs。

参数 类型 描述
AccountName 字符串 访问存储的 Azure Blob Storage 账户的名称。
AccountKey 字符串 用于访问容器的存储账户访问密钥。
ContainerName 字符串 存储缓存数据的存储容器的名称。
StorageDomain 字符串 用于服务 Azure 存储端点的域名(可选)。默认为 blob.core.windows.net

示例:

[runners.cache]
  Type = "azure"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.azure]
    AccountName = "<AZURE STORAGE ACCOUNT NAME>"
    AccountKey = "<AZURE STORAGE ACCOUNT KEY>"
    ContainerName = "runners-cache"
    StorageDomain = "blob.core.windows.net"

[runners.kubernetes] 部分

引入于极狐GitLab Runner v1.6.0。

以下参数定义 Kubernetes 行为。 更多参数请参见 Kubernetes 执行器文档

参数 类型 描述
host 字符串 可选。Kubernetes 主机 URL。如果未指定,Runner 会试着自动发现。
cert_file 字符串 可选。Kubernetes 认证证书。
key_file 字符串 可选。Kubernetes 认证私钥。
ca_file 字符串 可选。Kubernetes 认证 CA 证书。
image 字符串 如未指定,作业使用的默认 Docker 镜像。
allowed_images 阵列 .gitlab-ci.yml 中允许的镜像的通配符列表。如果不存在,则允许所有镜像(相当于 ["*/*:*"])。和 DockerKubernetes 执行器一起使用。
allowed_services 阵列 .gitlab-ci.yml 中允许的服务的通配符列表。如果不存在,则允许所有镜像(相当于 ["*/*:*"])。和 DockerKubernetes 执行器一起使用。
namespace 字符串 运行 Kubernetes 作业的命名空间。
privileged 布尔 启用特权标志,运行所有容器。
allow_privilege_escalation 布尔 可选。启用 allowPrivilegeEscalation 标志,启用所有容器。
node_selector 表格 string=stringkey=value 对的 table。限制匹配所有 key=value 对的 Kubernetes 节点的 pod 的创建。
image_pull_secrets 阵列 包含 Kubernetes docker-registry 秘密名称的项目阵列,该秘密名称用于验证从私有镜像库拉取的 Docker 镜像。

示例:

[runners.kubernetes]
  host = "https://45.67.34.123:4892"
  cert_file = "/etc/ssl/kubernetes/api.crt"
  key_file = "/etc/ssl/kubernetes/api.key"
  ca_file = "/etc/ssl/kubernetes/ca.crt"
  image = "golang:1.8"
  privileged = true
  allow_privilege_escalation = true
  image_pull_secrets = ["docker-registry-credentials", "optional-additional-credentials"]
  allowed_images = ["ruby:*", "python:*", "php:*"]
  allowed_services = ["postgres:9.4", "postgres:latest"]
  [runners.kubernetes.node_selector]
    gitlab = "true"

Helper 镜像

当您使用 dockerdocker+machinekubernetes 执行器,极狐GitLab Runner 使用特定容器处理 Git、产物和缓存操作。这个容器从名为 helper image 的镜像创建。

Helper 镜像对 amd64、 arm、 arm64、 s390x 和 ppc64le 架构可用。它包含 gitlab-runner-helper 二进制,它是极狐GitLab Runner 二进制的特殊编译,仅包括可用命令的子集和 Git、Git LFS 和 SSL 证书存储。

当极狐GitLab Runner 从 DEB/RPM 安装包安装,支持的架构的镜像安装在主机上。 当 Runner 准备执行作业,如果 Docker Engine 上没有特定版本(基于 Runner 的 Git 修订)中的镜像,会自动加载。 dockerdocker+machine 执行器都以这种方式工作。

对于 alpine 类型,安装包中只包括默认的 alpine 类型镜像。所有其他的类型都从镜像库下载。

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

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

两种情况下,极狐GitLab Runner 都下载 Helper 镜像。 极狐GitLab Runner 修订和架构定义下载的标签。

Kubernetes on Arm 的 Helper 镜像配置

要在 arm64 Kubernetes 集群上使用 arm64 Helper 镜像,请在配置文件中设置以下值。

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

使用老版本 Alpine Linux 的 Runner 镜像

引入于极狐GitLab Runner 14.5。

镜像和很多版本的 Alpine Linux进行构建,所以您可以使用新版本的 Alpine,但是同时也使用老版本。 对于 Helper 镜像,更改 helper_image_flavor 或阅读 Helper 镜像部分。

对于极狐GitLab Runner 镜像,遵循同样的逻辑,alpine、alpine3.15、alpine3.16、alpine3.17、alpine3.18 或 alpine-latest 在版本前、镜像中用作前缀:

docker pull gitlab/gitlab-runner:alpine3.18-v16.1.0

Alpine pwsh 镜像

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

示例:

docker pull gitlab/gitlab-runner-helper:alpine3.18-x86_64-v16.1.0-pwsh

Helper 镜像库

在 15.0 及更高版本中,Helper 镜像是从极狐GitLab 容器镜像库中拉取的。

在 15.0 及更早版本中,您可以将 Helper 镜像配置为使用来自 Docker Hub 的镜像。要从极狐GitLab 镜像库中检索基本的 gitlab-runner-helper 镜像,请使用 helper-image 值:registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:x86_64-v ${CI_RUNNER_VERSION}

私有化部署实例还从 JihuLab.com 上的极狐GitLab 容器镜像库中拉取 Helper 镜像。要检查极狐GitLab 容器镜像库的状态,请参阅极狐GitLab 系统状态

覆盖 Helper 镜像

在某些情况下,您可能需要覆盖 Helper 镜像。这样做有很多原因:

  1. 为加速作业执行:在互联网连接缓慢的环境中,多次下载同样的镜像会增加执行作业的时间。从存储 gitlab/gitlab-runner-helper:XYZ 副本的本地镜像库下载 Helper 镜像会进行加速。

  2. 安全考量:您可能不会想要下载之前未经过检查的外部依赖。 或许有业务规则指导如何仅使用在本地仓库检查和存储的依赖。

  3. 无因特网访问构建环境:在一些情境下,作业会在专用封闭的网络下执行。 kubernetes 执行器并不适用,因为其中的镜像依然需要从 Kubernetes 集群可用的外部镜像库下载。

  4. 额外的软件: 您可能想要向 Helper 镜像安装一些额外的软件, 例如 openssh,以支持子模块可以使用 git+ssh 而不是 git+http 进行访问。

在这些情况下,您可以使用 dockerdocker+machinekubernetes 执行器可用的 helper_image 配置字段,配置自定义镜像。

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    helper_image = "my.registry.local/gitlab/gitlab-runner-helper:tag"

Helper 镜像的版本应该与极狐GitLab Runner 的版本严格耦合。 提供这些镜像的一个主要原因是极狐GitLab Runner 正在使用的是 gitlab-runner-helper 二进制。这个二进制从部分极狐GitLab Runner 源进行编译。其使用预计在两个二进制中相同的内部 API。

极狐GitLab Runner 默认引用 gitlab/gitlab-runner-helper:XYZ 镜像,其中 XYZ 基于极狐GitLab Runner 架构和 Git 修订。

[[runners]]
(...)
executor = "docker"
[runners.docker]
(...)
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 之前被上传到镜像库,否则作业会提示 “No such image” 的错误消息并失败。

在极狐GitLab Runner 13.2 及更高版本中,Helper 镜像会被 $CI_RUNNER_VERSION$CI_RUNNER_REVISION 打上标签。两个标签都有效且指向同一个镜像。

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    helper_image = "my.registry.local/gitlab/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}"

使用 PowerShell Core 时

包括 PowerShell Core 的 Linux Helper 镜像的额外版本,被打上 gitlab/gitlab-runner-helper:XYZ-pwsh 标签发布。

[runners.custom_build_dir] 部分

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

如果没有明确配置,这个功能对于 kubernetesdockerdocker+machine 执行器默认开启。对于所有其他执行器,默认禁用。

这个功能需要 GIT_CLONE_PATHrunners.builds_dir 定义的路径中。如果想使用 builds_dir,请使用 $CI_BUILDS_DIR 变量。

这个功能默认只对于 dockerkubernetes 执行器开启, 因为它们提供了一种将资源分开的好方法。 这个功能对于任何执行器都明确开启,但通过共享 builds_dir 且拥有 concurrent > 1 的执行器使用时需要注意。

参数 类型 描述
enabled 布尔 允许用户为作业定义自定义构建目录。

示例:

[runners.custom_build_dir]
  enabled = true

默认构建目录

极狐GitLab Runner 将仓库克隆到构建目录基本路径下的一个路径中。 这个基本目录的默认位置取决于执行器。对于:

  • KubernetesDockerDocker Machine 执行器,它是容器内部的 /builds
  • Shell 执行器,它是 $PWD/builds
  • SSHVirtualBoxParallels 执行器,它是配置为处理目标机器 SSH 连接的用户的主目录中的 ~/builds
  • 自定义 执行器,不提供默认值,并且必须明确配置,否则会导致作业失败。

使用的构建目录可以由用户使用 builds_dir 设置进行明确定义。

note 如果您想克隆到自定义目录,您还可以指定 GIT_CLONE_PATH,以下规定不适用。

极狐GitLab Runner 将构建目录用于它所运行的所有作业,但使用特定模式 {builds_dir}/$RUNNER_TOKEN_KEY/$CONCURRENT_ID/$NAMESPACE/$PROJECT_NAME 进行嵌套。 例如:/builds/2mn-ncv-/0/user/playground

极狐GitLab Runner 不会阻止您在构建目录中进行存储。 例如,您可以将工具存储在可以在 CI 执行期间使用的 /builds/tools 中。 我们十分不鼓励这样的做法,您不应该在构建目录中存储任何东西。 极狐GitLab Runner 应该对其拥有完全控制权,并在这种情况下不做稳定性保证。 如果您有 CI 所需要的依赖项,我们建议您将其安装在其他地方。

[runners.referees] 部分

  • 引入于极狐GitLab Runner 12.7。
  • 需要极狐GitLab v12.6 及更高版本。

使用极狐GitLab Runner Referee 将额外作业监控数据传递到极狐GitLab。Referee 是 Runner Manager 中查询和收集作业相关的额外数据的 worker。 结果作为作业产物被上传到极狐GitLab。

使用 Metrics Runner Referee

运行作业的机器或容器展示 Prometheus指标,极狐GitLab Runner 可以在作业的整个持续时间内查询 Prometheus 服务器。收到指标后,它们作为可用于后续分析的作业产物被上传。

只有 docker-machine 执行器 支持 Referee。

为极狐GitLab Runner 配置 Metrics Runner Referee

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

设置 描述
prometheus_address 从极狐GitLab Runner 实例收集指标的服务器。作业完成时,它必须可以被 Runner Manager 访问。
query_interval 与作业关联的 Prometheus 实例为时间系列数据被查询的频率,被定义为时间间隔(单位为秒)。
queries 每个时间间隔执行的 PromQL 查询阵列。

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

[[runners]]
  [runners.referees]
    [runners.referees.metrics]
      prometheus_address = "http://localhost:9090"
      query_interval = 10
      metric_queries = [
        "arp_entries:rate(node_arp_entries{{selector}}[{interval}])",
        "context_switches:rate(node_context_switches_total{{selector}}[{interval}])",
        "cpu_seconds:rate(node_cpu_seconds_total{{selector}}[{interval}])",
        "disk_read_bytes:rate(node_disk_read_bytes_total{{selector}}[{interval}])",
        "disk_written_bytes:rate(node_disk_written_bytes_total{{selector}}[{interval}])",
        "memory_bytes:rate(node_memory_MemTotal_bytes{{selector}}[{interval}])",
        "memory_swap_bytes:rate(node_memory_SwapTotal_bytes{{selector}}[{interval}])",
        "network_tcp_active_opens:rate(node_netstat_Tcp_ActiveOpens{{selector}}[{interval}])",
        "network_tcp_passive_opens:rate(node_netstat_Tcp_PassiveOpens{{selector}}[{interval}])",
        "network_receive_bytes:rate(node_network_receive_bytes_total{{selector}}[{interval}])",
        "network_receive_drops:rate(node_network_receive_drop_total{{selector}}[{interval}])",
        "network_receive_errors:rate(node_network_receive_errs_total{{selector}}[{interval}])",
        "network_receive_packets:rate(node_network_receive_packets_total{{selector}}[{interval}])",
        "network_transmit_bytes:rate(node_network_transmit_bytes_total{{selector}}[{interval}])",
        "network_transmit_drops:rate(node_network_transmit_drop_total{{selector}}[{interval}])",
        "network_transmit_errors:rate(node_network_transmit_errs_total{{selector}}[{interval}])",
        "network_transmit_packets:rate(node_network_transmit_packets_total{{selector}}[{interval}])"
      ]

指标查询的格式为 canonical_name:query_string。查询串支持两种在执行中替换的变量:

设置 描述
{selector} 被特定极狐GitLab Runner 实例使用选择 Prometheus 中生成的指标的 label_name=label_value 对替换。
{interval} 用来自 Referee 的 [runners.referees.metrics] 配置的 query_interval 参数替换。

例如,使用 docker-machine 执行器的共享极狐GitLab Runner 环境拥有类似于 node=shared-runner-123{selector}