Advanced configuration

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: JihuLab.com, 极狐GitLab私有化部署, 极狐GitLab Dedicated

要改变极狐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 信号后重新加载配置。

配置验证#

History

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

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

全局部分#

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

设置描述
concurrent限制所有注册 runners 可以同时运行的作业数量。每个 [[runners]] 部分可以定义其自己的限制,但此值为所有这些值的组合设置一个最大值。例如,值为 10 意味着不超过 10 个作业可以同时运行。0 是被禁止的。如果使用此值,runner 进程会因严重错误退出。查看此设置如何与 Docker Machine executorInstance executorDocker Autoscaler executorrunners.custom_build_dir 配置 一起工作。
log_level定义日志级别。选项有 debuginfowarnerrorfatalpanic。此设置的优先级低于命令行参数 --debug-l--log-level 设置的级别。
log_format指定日志格式。选项有 runnertextjson。此设置的优先级低于命令行参数 --log-format 设置的格式。默认值是 runner,其中包含用于着色的 ANSI 转义码。
check_interval定义 runner 检查新作业的间隔时间(以秒为单位)。默认值为 3。如果设置为 0 或更低,则使用默认值。
sentry_dsn启用将所有系统级错误跟踪到 Sentry。
connection_max_ageTLS 保持连接与极狐GitLab 服务器的最大持续时间(在重新连接之前)。默认值为 15m(15 分钟)。如果设置为 0 或更低,则连接尽可能长时间保持。
listen_address定义 Prometheus 指标 HTTP 服务器应监听的地址 (<host>:<port>)。
shutdown_timeout直到 强制关机操作 超时并退出进程的秒数。默认值为 30。如果设置为 0 或更低,则使用默认值。

这是一个配置示例:

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-1runner-2)。极狐GitLab Runner 每 10 秒发送一个请求,并休眠五秒:

  1. 获取 check_interval 值(10s)。
  2. 获取 runners 列表(runner-1runner-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-1runner-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_addressadvertise_address,使用格式 host:port,其中 host 是 IP 地址 (127.0.0.1:8093) 或域 (my-runner.example.com:8093)。runner 使用此信息创建一个 TLS 证书用于安全连接。
  • 确保极狐GitLab 可以连接到 listen_addressadvertise_address 中定义的 IP 地址和端口。
  • 确保 advertise_address 是一个公共 IP 地址,除非您已启用应用程序设置 allow_local_requests_from_web_hooks_and_services
设置描述
listen_addresssession server 的内部 URL。
advertise_address访问 session server 的 URL。极狐GitLab Runner 将其暴露给极狐GitLab。如果未定义,则使用 listen_address
session_timeout作业完成后 session 可以保持活动状态的秒数。超时阻止作业完成。默认值为 1800(30 分钟)。

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

当您的 runner 实例已经在运行时,您可能需要执行 gitlab-runner restart 以使 [session_server] 部分中的更改生效。

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

[[runners]] 部分#

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

设置描述
namerunner 的描述。仅供参考。
url极狐GitLab 实例 URL。
tokenrunner 的身份验证令牌,在 runner 注册期间获取。与注册令牌不同
tls-ca-file使用 HTTPS 时,包含用于验证对等方的证书的文件。参见 自签名证书或自定义认证机构文档
tls-cert-file使用 HTTPS 时,包含用于与对等方进行身份验证的证书的文件。
tls-key-file使用 HTTPS 时,包含用于与对等方进行身份验证的私钥的文件。
limit限制此注册 runner 可以同时处理的作业数量。0(默认)表示不限制。查看此设置如何与 Docker MachineInstanceDocker Autoscaler 执行器一起工作。
executorrunner 用来运行 CI/CD 作业的主机操作系统上的环境或命令处理器。有关更多信息,请参见 executors
shell用于生成脚本的 shell 名称。默认值是 平台相关 的。
builds_dir在所选执行器的上下文中存储构建的目录的绝对路径。例如,本地、Docker 或 SSH。
cache_dir在所选执行器的上下文中存储构建缓存的目录的绝对路径。例如,本地、Docker 或 SSH。如果使用 docker 执行器,则此目录需要包含在其 volumes 参数中。
environment追加或覆盖环境变量。
request_concurrency限制从极狐GitLab 获取新作业的并发请求数量。默认值为 1
output_limit构建日志的最大大小(以千字节为单位)。默认值为 4096(4 MB)。
pre_get_sources_script在更新 Git 存储库和更新子模块之前,在 runner 上执行的命令。用于首先调整 Git 客户端配置,例如。要插入多个命令,请使用(三引号)多行字符串或 \n 字符。
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禁用 debug tracing。如果设置为 true,即使 CI_DEBUG_TRACE 设置为 true,调试日志(跟踪)仍然禁用。
clean_git_config清理 Git 配置。有关更多信息,请参见 清理 Git 配置
referees传递其结果作为作业产物给极狐GitLab 的额外作业监控 worker。
unhealthy_requests_limit在 runner worker 被禁用之前,对新作业请求的 unhealthy 响应次数。
unhealthy_intervalrunner worker 在超过 unhealthy 请求限制后被禁用的持续时间。支持诸如 '3600 s'、'1 h 30 min' 等语法。
job_status_final_update_retry_limit极狐GitLab Runner 在将最终作业状态推送到极狐GitLab 实例时可以重试的最大次数。

示例:

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

clone_url 不影响 Git LFS 端点或产物上传或下载。

修改 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_limitunhealthy_interval 的工作原理#

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

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

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

执行器#

以下是可用的执行器。

执行器所需配置作业运行位置
shell本地 shell。默认执行器。
docker[runners.docker]Docker Engine一个 Docker 容器。
docker-windows[runners.docker]Docker Engine一个 Windows Docker 容器。
ssh[runners.ssh]SSH,远程。
parallels[runners.parallels][runners.ssh]Parallels VM,但通过 SSH 连接。
virtualbox[runners.virtualbox][runners.ssh]VirtualBox VM,但通过 SSH 连接。
docker+machine[runners.docker][runners.machine]类似于 docker,但使用 自动扩展 Docker machines
kubernetes[runners.kubernetes]Kubernetes pods。
docker-autoscaler[docker-autoscaler][runners.autoscaler]类似于 docker,但使用自动扩展实例在容器中运行 CI/CD 作业。
instance[docker-autoscaler][runners.autoscaler]类似于 shell,但使用自动扩展实例直接在主机实例上运行 CI/CD 作业。

Shells#

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

Shell描述
bash生成 Bash(Bourne-shell)脚本。所有命令在 Bash 上下文中执行。默认适用于所有 Unix 系统。
sh生成 Sh(Bourne-shell)脚本。所有命令在 Sh 上下文中执行。bash 的回退选项适用于所有 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)。启用后,将使用 "Double Quotes",这是一种符合 POSIX 的 shell 转义机制。

[runners.docker] 部分#

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

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

参数描述示例
allowed_images可以在 .gitlab-ci.yml 文件中指定的镜像的通配符列表。如果不存在,则允许所有镜像(相当于 ["*/*:*"])。与 DockerKubernetes 执行器一起使用。["ruby:*", "python:*", "php:*"]
allowed_privileged_imagesallowed_images 的通配符子集,当 privileged 启用时以特权模式运行。如果不存在,则允许所有镜像(相当于 ["*/*:*"])。与 Docker 执行器一起使用。
allowed_pull_policies可以在 .gitlab-ci.yml 文件或 config.toml 文件中指定的拉取策略列表。如果未指定,则仅允许在 pull-policy 中指定的拉取策略。与 Docker 执行器一起使用。
allowed_services可以在 .gitlab-ci.yml 文件中指定的服务的通配符列表。如果不存在,则允许所有镜像(相当于 ["*/*:*"])。与 DockerKubernetes 执行器一起使用。["postgres:9", "redis:*", "mysql:*"]
allowed_privileged_servicesallowed_services 的通配符子集,当 privilegedservices_privileged 启用时允许以特权模式运行。如果不存在,则允许所有镜像(相当于 ["*/*:*"])。与 Docker 执行器一起使用。
cache_dirDocker 缓存应存储的目录。此路径可以是相对于当前工作目录的绝对路径。有关详细信息,请参见 disable_cache
cap_add向容器添加其他 Linux 功能。["NET_ADMIN"]
cap_drop从容器中删除其他 Linux 功能。["DAC_OVERRIDE"]
cpuset_cpus控制组的 CpusetCpus。一个字符串。"0,1"
cpuset_mems控制组的 CpusetMems。一个字符串。"0,1"
cpu_shares用于设置相对 CPU 使用率的 CPU 份额数。默认值为 1024
cpusCPU 数量(适用于 Docker 1.13 或更高版本)。一个字符串。"2"
devices与容器共享的其他主机设备。["/dev/net/tun"]
device_cgroup_rules自定义设备 cgroup 规则(适用于 Docker 1.28 或更高版本)。
disable_cacheDocker 执行器有两个缓存级别:一个全局缓存(如任何其他执行器)和一个基于 Docker 卷的本地缓存。此配置标志仅对本地缓存起作用,禁用自动创建的(未映射到主机目录)缓存卷的使用。换句话说,它只会阻止创建一个保存构建临时文件的容器,但不会禁用缓存如果 runner 配置为分布式缓存模式
disable_entrypoint_overwrite禁用镜像入口点覆盖。
dns容器使用的 DNS 服务器列表。["8.8.8.8"]
dns_searchDNS 搜索域的列表。
extra_hosts应在容器环境中定义的主机。["other-host:127.0.0.1"]
gpusDocker 容器的 GPU 设备。使用与 docker CLI 相同的格式。查看 Docker 文档 了解详细信息。需要 配置以启用 GPU
group_add为容器进程运行添加其他组。["docker"]
helper_image(高级)默认的辅助镜像 用于克隆存储库和上传产物。
helper_image_flavor设置辅助镜像风格(alpinealpine3.18alpine3.19alpine3.21alpine-latestubi-fipsubuntu)。默认为 alpinealpine 风格使用与 alpine3.21 相同的版本。
helper_image_autoset_arch_and_os使用底层操作系统设置辅助镜像的架构和操作系统。
host自定义 Docker 端点。默认是 DOCKER_HOST 环境或 unix:///var/run/docker.sock
hostnameDocker 容器的自定义主机名。
image用于运行作业的镜像。"ruby:3.3"
links应与运行作业的容器链接的容器。["mysql_container:mysql"]
memory内存限制。一个字符串。"128m"
memory_swap总内存限制。一个字符串。"256m"
memory_reservation内存软限制。一个字符串。"64m"
network_mode将容器添加到自定义网络中。
mac_address容器 MAC 地址92:d0:c6:0a:29:33
oom_kill_disable如果发生内存不足(OOM)错误,请勿终止容器中的进程。
oom_score_adjustOOM 分数调整。正数意味着更早终止进程。
privileged使容器以特权模式运行。不安全。false
services_privileged允许服务以特权模式运行。如果未设置(默认),则使用 privileged 值。与 Docker 执行器一起使用。不安全。
pull_policy镜像拉取策略:neverif-not-presentalways(默认)。查看 拉取策略文档 了解详细信息。您还可以添加多个拉取策略重试失败的拉取限制拉取策略
runtimeDocker 容器的运行时。
isolation容器隔离技术(defaulthypervprocess)。仅适用于 Windows。
security_opt安全选项(docker run 中的 --security-opt)。采用 : 分隔的键/值列表。
shm_size镜像的共享内存大小(以字节为单位)。300000
sysctlssysctl 选项。
tls_cert_path用于存储和使用 ca.pemcert.pemkey.pem 以与 Docker 建立安全 TLS 连接的目录。与 boot2docker 一起使用此设置。在 macOS 上 /Users/<username>/.boot2docker/certs
tls_verify启用或禁用对 Docker 守护进程连接的 TLS 验证。默认禁用。默认情况下,极狐GitLab Runner 通过 SSH 连接到 Docker Unix 套接字。Unix 套接字不支持 RTLS,并通过 SSH 通信以提供加密和身份验证。通常不需要启用 tls_verify,并且需要额外的配置。要启用 tls_verify,守护进程必须监听端口(而不是默认的 Unix 套接字),并且极狐GitLab Runner Docker 主机必须使用守护进程监听的地址。
user在容器中以指定用户身份运行所有命令。
userns_mode启用用户命名空间重新映射选项时,容器和 Docker 服务的用户命名空间模式。适用于 Docker 1.10 或更高版本。有关详细信息,请参阅 Docker 文档
ulimit传递给容器的 Ulimit 值。使用与 Docker --ulimit 标志相同的语法。
volumes应挂载的其他卷。与 Docker -v 标志相同的语法。["/data", "/home/project/cache"]
volumes_from<container name>[:<access_level>] 形式继承自其他容器的卷列表。访问级别默认为读写,但可以手动设置为 ro(只读)或 rw(读写)。["storage_container:ro"]
volume_driver用于容器的卷驱动程序。
wait_for_services_timeout等待 Docker 服务的时间。设置为 -1 以禁用。默认值为 3030
container_labels要添加到 runner 创建的每个容器的标签集。标签值可以包含用于扩展的环境变量。
services_limit设置每个作业允许的最大服务数。-1(默认)表示没有限制。
service_cpuset_cpus包含要用于服务的 cgroups CpusetCpus 的字符串值。
service_cpu_shares用于设置服务相对 CPU 使用率的 CPU 份额数(默认: 1024)。
service_cpus服务的 CPU 数量的字符串值。适用于 Docker 1.13 或更高版本。
service_gpusDocker 容器的 GPU 设备。使用与 docker CLI 相同的格式。查看 Docker 文档 了解详细信息。需要 配置以启用 GPU
service_memory服务的内存限制的字符串值。
service_memory_swap服务的总内存限制的字符串值。
service_memory_reservation服务的内存软限制的字符串值。

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

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

参数描述示例
name要作为服务运行的镜像名称。"registry.example.com/svc1"
alias可以用于访问服务的附加别名名称"svc1"
entrypoint应作为容器入口点执行的命令或脚本。语法类似于 Dockerfile ENTRYPOINT 指令,其中每个 shell 标记是数组中的一个单独字符串。引入于 极狐GitLab Runner 13.6["entrypoint.sh"]
command应用作容器命令的命令或脚本。语法类似于 Dockerfile CMD 指令,其中每个 shell 标记是数组中的一个单独字符串。引入于 极狐GitLab Runner 13.6["executable","param1","param2"]
environment为服务容器追加或覆盖环境变量。["ENV1=value1", "ENV2=value2"]

示例:

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 拉取镜像的方式

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

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。

参数描述
base_name被克隆的 Parallels 虚拟机的名称。
template_nameParallels 虚拟机链接模板的自定义名称。可选。
disable_snapshots如果禁用,当作业完成时,虚拟机将被销毁。
allowed_images允许的 image/base_name 值的列表,表示为正则表达式。有关更多详细信息,请参阅覆盖基础虚拟机镜像部分。

示例:

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

参数说明
base_name被克隆的 VirtualBox 虚拟机的名称。
base_snapshot要从中创建链接克隆的虚拟机的特定快照的名称或 UUID。如果此值为空或省略,则使用当前快照。如果不存在当前快照,则会创建一个快照,除非 disable_snapshots 为 true,在这种情况下,将进行基础虚拟机的完整克隆。
base_folder保存新虚拟机的文件夹。如果此值为空或省略,则使用默认虚拟机文件夹。
disable_snapshots如果禁用,当作业完成时,虚拟机将被销毁。
allowed_images允许的 image/base_name 值的列表,表示为正则表达式。有关更多详细信息,请参阅覆盖基础虚拟机镜像部分。
start_type启动虚拟机时的图形前端类型。

示例:

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

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

覆盖基础虚拟机镜像#

History
    • 在极狐GitLab Runner 14.2 中引入。

对于 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_vm1allowed_vm2。任何其他尝试都会导致错误。

runners.ssh 部分#

以下参数定义 SSH 连接。

参数描述
host连接到的主机。
port端口。默认是 22
user用户名。
password密码。
identity_fileSSH 私钥的文件路径(id_rsaid_dsaid_edcsa)。文件必须以未加密的形式存储。
disable_strict_host_key_checking此值确定 runner 是否应该使用严格的主机密钥检查。默认是 true。在极狐GitLab 15.0 中,默认值或未指定的值为 false

示例:

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 执行器自动缩放配置

参数描述
MaxGrowthRate可以并行添加到 runner 的最大机器数量。默认是 0(无限制)。
IdleCount需要创建并处于 Idle 状态的机器数量。
IdleScaleFactor处于 Idle 状态的机器数量作为使用中机器数量的一个因子。必须是浮点数格式。有关更多详细信息,请参阅自动缩放文档。默认是 0.0
IdleCountMin当使用 IdleScaleFactor 时,需创建并处于 Idle 状态的机器的最小数量。默认是 1。
IdleTime机器处于 Idle 状态的时间(以秒为单位)然后被移除。
[[runners.machine.autoscaling]]多个部分,每个部分包含自动缩放配置的覆盖。选择与当前时间匹配的表达式的最后一个部分。
OffPeakPeriods已弃用:调度程序处于 OffPeak 模式的时间段。cron 风格模式的数组(在下方描述)。
OffPeakTimezone已弃用:OffPeakPeriods 中给出的时间的时区。类似 Europe/Berlin 的时区字符串。如果省略或为空,默认使用主机的区域系统设置。极狐GitLab Runner 尝试在 ZONEINFO 环境变量指向的目录或未压缩的 zip 文件中查找时区数据库,然后在 Unix 系统的已知安装位置查找,最后在 $GOROOT/lib/time/zoneinfo.zip 中查找。
OffPeakIdleCount已弃用:类似于 IdleCount,但用于 Off Peak 时间段。
OffPeakIdleTime已弃用:类似于 IdleTime,但用于 Off Peak 时间段。
MaxBuilds在机器被移除之前的最大作业(构建)数量。
MachineName机器的名称。必须包含 %s,它将被唯一的机器标识符替换。
MachineDriverDocker Machine 的 driver。详情请参阅 Docker Machine 配置中的云提供商部分
MachineOptionsDocker Machine 的 MachineDriver 选项。有关更多信息,请参阅支持的云提供商。有关 AWS 的所有选项的更多信息,请参阅 Docker Machine 存储库中的 AWSGCP 项目。

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

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

参数描述
Periods此计划活动期间的时间段。cron 风格模式的数组(在下方描述)。
IdleCount需要创建并处于 Idle 状态的机器数量。
IdleScaleFactor(实验)处于 Idle 状态的机器数量作为使用中机器数量的一个因子。必须是浮点数格式。有关更多详细信息,请参阅自动缩放文档。默认是 0.0
IdleCountMin当使用 IdleScaleFactor 时,需创建并处于 Idle 状态的机器的最小数量。默认是 1。
IdleTime机器处于 Idle 状态的时间(以秒为单位)然后被移除。
TimezonePeriods 中给出的时间的时区。类似 Europe/Berlin 的时区字符串。如果省略或为空,默认使用主机的区域系统设置。极狐GitLab Runner 尝试在 ZONEINFO 环境变量指向的目录或未压缩的 zip 文件中查找时区数据库,然后在 Unix 系统的已知安装位置查找,最后在 $GOROOT/lib/time/zoneinfo.zip 中查找。

示例:

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 部分#

参数类型描述
allowed_images字符串启用虚拟机隔离时,allowed_images 控制作业允许指定哪些镜像。

runners.autoscaler 部分#

History
    • 在极狐GitLab Runner v15.10.0 中引入。

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

参数描述
capacity_per_instance单个实例可以同时执行的作业数量。
max_use_count实例在被安排移除之前可以使用的最大次数。
max_instances允许的最大实例数量,这与实例状态(待定、运行、删除)无关。默认值:0(无限制)。
plugin要使用的 fleeting 插件。有关如何安装和引用插件的详细信息,请参阅 安装 fleeting 插件
delete_instances_on_shutdown指定极狐GitLab Runner 关闭时是否删除所有预留的实例。默认:false。在 极狐GitLab Runner 15.11 中引入
instance_ready_command在自动缩放器预留的每个实例上执行此命令以确保它已准备好使用。失败会导致实例被移除。在 极狐GitLab Runner 16.11 中引入。
update_interval检查 fleeting 插件进行实例更新的间隔。默认值:1m(1 分钟)。在 极狐GitLab Runner 16.11 中引入。
update_interval_when_expecting在期待状态变化时检查 fleeting 插件进行实例更新的间隔。例如,当实例已预留且 runner 等待从 pending 过渡到 running 时)。默认值:2s(2 秒)。在 极狐GitLab Runner 16.11 中引入。

如果 instance_ready_command 在空闲缩放规则下频繁失败,实例可能会被移除并创建得比 runner 接受作业的速度还快。为了支持缩放节流,极狐GitLab 17.0 中添加了指数退避。

自动缩放器配置选项不会随着配置更改而重新加载。但是,在极狐GitLab 17.5.0 或更高版本中,配置更改时重新加载 [[runners.autoscaler.policy]] 条目。

runners.autoscaler.plugin_config 部分#

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

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

runners.autoscaler.scale_throttle 部分#

History
    • 在极狐GitLab Runner v17.0.0 中引入。
参数描述
limit每秒可以预留的新实例的速率限制。-1 表示无限。默认值(0),将限制设置为 100
burst新实例的突发限制。默认值是 max_instanceslimit,当未设置 max_instances 时。如果 limit 是无限的,则忽略 burst

limitburst 之间的关系#

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

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

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

例如,如果 limit1burst60

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

runners.autoscaler.connector_config 部分#

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

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

参数描述
os实例的操作系统。
arch实例的架构。
protocolsshwinrmwinrm+https。如果检测到 Windows,则默认使用 winrm
protocol_port基于指定协议建立连接的端口。默认值为 ssh:220winrm+http:5985winrm+https:5986
username用于连接的用户名。
password用于连接的密码。
key_path用于连接或动态预留凭据的 TLS 密钥。
use_static_credentials禁用自动凭据预留。默认值:false
keepalive连接保持活动的持续时间。
timeout连接超时时间。
use_external_addr是否使用插件提供的外部地址。如果插件仅返回内部地址,则无论此设置如何,它都会被使用。默认值:false

runners.autoscaler.state_storage 部分#

  • 状态:Beta
History
    • 在极狐GitLab Runner 17.5.0 中引入。

如果极狐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 容器。

参数描述
enabled是否启用状态存储。默认:false
dir状态存储目录。此处每个 runner 配置条目都有一个子目录。默认:极狐GitLab Runner 配置文件目录中的 .taskscaler
keep_instance_with_acquisitions是否删除具有活动作业的实例。默认:false

runners.autoscaler.policy 部分#

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

参数描述
periods一个 UNIX-cron 格式化字符串的数组,用于表示此策略启用的时间段。默认:* * * * *
timezone评估 UNIX-cron 时间段时使用的时区。默认:系统的本地时区。
idle_count我们希望立即为作业提供的目标空闲容量。
idle_time实例可以处于空闲状态的时间。
scale_factor我们希望立即为作业提供的目标空闲容量,作为 idle_count 之外的当前使用容量的一个因子。默认值为 0.0
scale_factor_limitscale_factor 计算可以产生的最大容量。

为了决定是否移除空闲实例,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 作业表示一个时间范围。例如:

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

runners.autoscaler.vm_isolation 部分#

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

参数描述
enabled指定是否启用虚拟机隔离。默认:false
nesting_hostnesting 守护进程主机。
nesting_confignesting 配置,它被序列化为 JSON 并发送到 nesting 守护进程。
image如果没有指定作业镜像,则由 nesting 守护进程使用的默认镜像。

runners.autoscaler.vm_isolation.connector_config 部分#

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

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 部分#

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

参数类型描述
Type字符串之一:s3gcsazure
Path字符串要添加到缓存 URL 的路径名称。
Shared布尔型启用 runner 之间的缓存共享。默认是 false
MaxUploadedArchiveSizeint64上传到云存储的缓存归档的限制,以字节为单位。恶意行为者可以绕过此限制,因此 GCS 适配器通过签名 URL 中的 X-Goog-Content-Length-Range 标头强制执行。你还应该在云存储提供商处设置限制。

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

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

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

设置TOML 字段register 的 CLI 选项register 的环境变量
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-cache-shared
$CACHE_SHARED
S3.ServerAddress[runners.cache.s3] -> ServerAddress

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

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

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

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

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

在 12.0 之前,$S3_SECRET_KEY
S3.SessionToken[runners.cache.s3] -> SessionToken--cache-s3-session-token$CACHE_S3_SESSION_TOKEN
S3.BucketName[runners.cache.s3] -> BucketName

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

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

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

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

在 12.0 之前,[runners.cache] -> 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
S3.ServerSideEncryption[runners.cache.s3] -> ServerSideEncryption--cache-s3-server-side-encryption$CACHE_S3_SERVER_SIDE_ENCRYPTION
S3.ServerSideEncryptionKeyID[runners.cache.s3] -> ServerSideEncryptionKeyID--cache-s3-server-side-encryption-key-id$CACHE_S3_SERVER_SIDE_ENCRYPTION_KEY_ID
S3.DualStack[runners.cache.s3] -> DualStack--cache-s3-dual-stack$CACHE_S3_DUAL_STACK
S3.Accelerate[runners.cache.s3] -> Accelerate--cache-s3-accelerate$CACHE_S3_ACCELERATE
S3.PathStyle[runners.cache.s3] -> PathStyle--cache-s3-path-style$CACHE_S3_PATH_STYLE
S3.RoleARN[runners.cache.s3] -> RoleARN--cache-s3-role-arn$CACHE_S3_ROLE_ARN
S3.UploadRoleARN[runners.cache.s3] -> UploadRoleARN--cache-s3-upload-role-arn$CACHE_S3_UPLOAD_ROLE_ARN
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 存储用于缓存。

参数类型描述
ServerAddress字符串S3 兼容服务器的 host:port。如果你使用的是 AWS 以外的服务器,请查阅存储产品文档以确定正确的地址。对于 DigitalOcean,地址必须采用 spacename.region.digitaloceanspaces.com 格式。
AccessKey字符串为你的 S3 实例指定的访问密钥。
SecretKey字符串为你的 S3 实例指定的秘密密钥。
SessionToken字符串使用临时凭据时为你的 S3 实例指定的会话令牌。
BucketName字符串存储缓存的存储桶名称。
BucketLocation字符串S3 区域的名称。
Insecure布尔型如果 S3 服务可通过 HTTP 获得,则设置为 true。默认是 false
AuthenticationType字符串设置为 iamaccess-key。如果提供了 ServerAddressAccessKeySecretKey,则默认是 access-key。如果缺少 ServerAddressAccessKeySecretKey,则默认为 iam
ServerSideEncryption字符串使用 S3 的服务器端加密类型。在极狐GitLab 15.3 及更高版本中,可用类型为 S3KMS。在极狐GitLab 17.5 及更高版本中,支持 DSSE-KMS
ServerSideEncryptionKeyID字符串使用 KMS 加密时用于加密的 KMS 密钥的别名或 ID。如果使用别名,请在前面加上 alias/。在极狐GitLab 15.3 及更高版本中可用。
DualStack布尔型启用 IPv4 和 IPv6 端点。默认是 true。如果使用 AWS S3 Express,请禁用此设置。如果设置了 ServerAddress,极狐GitLab 将忽略此设置。在极狐GitLab 17.5 及更高版本中可用。
Accelerate布尔型启用 AWS S3 传输加速。如果 ServerAddress 配置为加速端点,极狐GitLab 会自动将其设置为 true。在极狐GitLab 17.5 及更高版本中可用。
PathStyle布尔型启用路径风格访问。默认情况下,极狐GitLab 根据 ServerAddress 值自动检测此设置。在极狐GitLab 17.5 及更高版本中可用。
UploadRoleARN字符串已弃用。请改用 RoleARN。指定一个 AWS 角色 ARN,可以与 AssumeRole 一起使用以生成时间限制的 PutObject S3 请求。启用 S3 分段上传。在极狐GitLab 17.5 及更高版本中可用。
RoleARN字符串指定一个 AWS 角色 ARN,可以与 AssumeRole 一起使用以生成时间限制的 GetObjectPutObject S3 请求。启用 S3 分段传输。在极狐GitLab 17.8 及更高版本中可用。

示例:

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"

如果未指定 ServerAddressAccessKeySecretKey 并且未提供 AuthenticationType,那么 S3 客户端将使用 gitlab-runner 实例可用的 IAM 实例配置文件。在 autoscale 配置中,这不是执行作业的按需机器。如果 ServerAddressAccessKeySecretKey 都已指定,但未提供 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 类型的 ServerSideEncryptionSSE-C 要求除了预签名 URL 外,还提供包含用户提供密钥的标头以进行下载请求。这意味着需要将密钥材料传递给作业,而密钥无法保证安全。这确实有可能泄漏解密密钥。

可以上传到 AWS S3 缓存的单个文件的最大大小为 5 GB。

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

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

属性描述
密钥类型对称
来源AWS_KMS
密钥规范SYMMETRIC_DEFAULT
密钥用途加密和解密

分配给 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 凭据可以访问指定 RoleARNAssumeRole

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

  • BucketName 中指定的桶的 s3:GetObject 访问。
  • BucketName 中指定的桶的 s3:PutObject 访问。
  • 如果启用了带有 KMS 或 DSSE-KMS 的服务器端加密,则需要 kms:Decryptkms: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 凭据(通过 AuthenticationTypeAccessKeySecretKey 指定)。

  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 时创建的默认服务账户:

      条件
      StringEqualsoidc.eks.<AWS_REGION>.amazonaws.com/id/<OIDC_ID>:subsystem:serviceaccount:<GITLAB_RUNNER_NAMESPACE>:<GITLAB_RUNNER_SERVICE_ACCOUNT>

使用 S3 Express One Zone 桶#

History
    • 引入于极狐GitLab Runner 17.5.0。

S3 Express One Zone 目录桶与 RoleARN 不兼容,因为 runner 管理器无法限制对特定对象的访问。

  1. 按照 Amazon 教程设置 S3 Express One Zone 桶。
  2. 使用 BucketNameBucketLocation 配置 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] 部分#

参数类型描述
CredentialsFilestringGoogle JSON 密钥文件的路径。仅支持 service_account 类型。如果配置,此值优先于直接在 config.toml 中配置的 AccessIDPrivateKey
AccessIDstring用于访问存储的 GCP 服务账户的 ID。
PrivateKeystring用于签署 GCS 请求的私钥。
BucketNamestring存储缓存数据的存储桶名称。

示例:

直接在 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] 部分#

History
    • 引入于极狐GitLab Runner 13.4.0。

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

参数类型描述
AccountNamestring用于访问存储的 Azure Blob 存储账户名称。
AccountKeystring用于访问容器的存储账户访问密钥。要从配置中省略 AccountKey,请使用 Azure 工作负载或托管身份
ContainerNamestring用于保存缓存数据的存储容器的名称。
StorageDomainstring用于服务 Azure 存储端点的域名用于服务 Azure 存储端点(可选)。默认值为 blob.core.windows.net

示例:

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 工作负载和托管身份#

History
    • 引入于极狐GitLab Runner v17.5.0。

要使用 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_accountgitlab-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] 部分#

History
    • 引入于极狐GitLab Runner v1.6.0。

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

参数类型描述
hoststring可选。Kubernetes 主机 URL。如果未指定,runner 尝试自动发现它。
cert_filestring可选。Kubernetes 身份验证证书。
key_filestring可选。Kubernetes 身份验证私钥。
ca_filestring可选。Kubernetes 身份验证 CA 证书。
imagestring当未指定图像时,用于作业的默认容器图像。
allowed_imagesarray容器图像的通配符列表,这些图像在 .gitlab-ci.yml 中是允许的。如果不存在,则允许所有图像(等同于 ["*/*:*"])。与 DockerKubernetes 执行器一起使用。
allowed_servicesarray.gitlab-ci.yml 中允许的服务通配符列表。如果不存在,则允许所有图像(等同于 ["*/*:*"])。与 DockerKubernetes 执行器一起使用。
namespacestring运行 Kubernetes 作业的命名空间。
privilegedboolean以启用特权标志运行所有容器。
allow_privilege_escalationboolean可选。以启用 allowPrivilegeEscalation 标志运行所有容器。
node_selectortable一个 string=stringkey=value 对的 table。将 pod 的创建限制为符合所有 key=value 对的 Kubernetes 节点。
image_pull_secretsarray包含 Kubernetes docker-registry secret 名称的项目数组,用于从私有注册表中认证拉取容器图像。
logs_base_dirstring要添加到生成路径中的基目录以存储构建日志。引入于极狐GitLab Runner 17.2。
scripts_base_dirstring要添加到生成路径中的基目录以存储构建脚本。引入于极狐GitLab Runner 17.2。
service_accountstring作业/执行器 pod 用于与 Kubernetes API 通信的默认服务账户。

示例:

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"

辅助镜像#

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

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

辅助镜像有几种风格:alpinealpine3.18alpine3.19alpine3.21alpine-latestubi-fipsubuntu。由于其小巧的体积,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 从 DEBRPM 包中安装时,支持的架构的镜像会安装在主机上。如果 Docker Engine 找不到指定的镜像版本,runner 会在运行作业之前自动下载它。dockerdocker+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 镜像#

History
    • 引入于极狐GitLab Runner 14.5。

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

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

对于极狐GitLab Runner 镜像,遵循相同的逻辑,其中 alpinealpine3.18alpine3.19alpine3.21alpine-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 配置字段配置自定义镜像,该字段可用于 dockerdocker+machinekubernetes 执行器:

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] 部分#

History
    • 引入于极狐GitLab Runner 11.10。

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

如果未明确配置此功能,则对于 kubernetesdockerdocker+machinedocker autoscalerinstance 执行器,此功能默认启用。对于所有其他执行器,默认情况下此功能禁用。

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

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

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

示例:

toml
[runners.custom_build_dir] enabled = true

默认构建目录#

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

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

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

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

极狐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 配置#

History
    • 引入于极狐GitLab Runner 17.10。

在每次构建的开始和结束时,极狐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

显式的 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],并添加以下字段:

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

以下是 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 格式。查询字符串支持两个在执行期间被替换的变量:

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

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