gitlab-Runner配置参数详解

Posted 2020-12-16 wu-wu

1、使用主机安装查看runner配置

　　$ cat /etc/gitlab-runner/config.toml

　　　　[session_server]（区段是一个系统 Runner 级别的配置，因此它应该在根级别指定，而不是在每个执行器上，也就是说，它应该在[[runners]]区段之外。会话服务器允许用户与运行程序负责的作业进行交互。交互式web终端就是一个很好的例子。）
　　　　| listen_address | 用于会话服务器的内部URL。 |
　　　　| advertise_address | Runner 将公开给GitLab用于访问会话服务器的URL。返回listen_address(如果没有定义)。 |
　　　　| session_timeout | 作业完成后会话保持活动的时间(这会阻止作业完成)，默认为1800(30分钟)。 |　

　　　　[runners]
　　　　| url | GitLab URL |
　　　　| token | Runner的通信令牌（请勿与注册令牌混淆） |
　　　　| tls-ca-file | 使用HTTPS时用于验证对等方的证书的文件 |
　　　　| tls-cert-file | 使用HTTPS时要与对等方进行身份验证的证书的文件 |
　　　　| tls-key-file | 使用HTTPS时要与对等方进行身份验证的私钥的文件 |
　　　　| limit | 限制此令牌可以同时处理多少个作业。0（默认）表示不限制 |
　　　　| executor | 构建项目要使用的执行器 |

　　　　　　| shell | 默认情况下，在本地运行build |

　　　　　　　　| bash | 生成Bash (Bourne-shell)脚本。在Bash上下文中执行的所有命令(所有Unix系统的缺省值) |
　　　　　　　　| sh | 生成Sh (Bourne-shell)脚本。在Sh上下文中执行的所有命令(所有Unix系统的bash后备命令) |
　　　　　　　　| cmd | 生成Windows批处理脚本。所有命令都在批处理上下文中执行(默认为Windows) |
　　　　　　　　| powershell | 生成Windows PowerShell脚本。所有命令都在PowerShell上下文中执行 |

　　　　　　| docker | 使用Docker容器运行构建。这需要`[runners.docker]`的存在。和`docker引擎`安装在一个系统上，运行程序将在该系统上运行作业。 |
　　　　　　| docker-windows | 使用Windows Docker容器运行构建。这需要`[runners.docker]`和`docker引擎`安装在Windows系统上。 |
　　　　　　| docker-ssh | 使用Docker容器运行构建，但是使用SSH连接到它——这需要`[runners.docker]` , `[runners.ssh]`和`Docker引擎`。注意:这将在`本地机器上运行docker容器`，它只是改变了命令在该容器内的运行方式。如果希望在外部机器上运行docker命令，那么应该更改 `runners.docker` 中的 `host` 参数。 |
　　　　　　| ssh | 使用SSH远程运行构建—这需要有`[runner.ssh]` |
　　　　　　| parallels | 使用Parallels VM运行构建，但是使用SSH连接到它——这需要[runners.parallels] and [runners.ssh] |
　　　　　　| virtualbox | 使用VirtualBox VM运行构建，但是使用SSH连接到它——这需要[runners.virtualbox] and [runners.ssh] |
　　　　　　| docker+machine | 像docker，但使用自动缩放的docker machines -这需要存在[runners.docker] and [runners.machine] |
　　　　　　| docker-ssh+machine | 与docker-ssh类似，但是使用自动伸缩的Docker机器——这需要[runners.docker] and [runners.machine] |
　　　　　　| kubernetes | 使用Kubernetes pod运行构建——这需要有`[runner.Kubernetes]`的存在。 |

　　　　| builds_dir | 目录的绝对路径，构建将存储在选定执行程序(本地、Docker、SSH)的上下文中。 |
　　　　| cache_dir | 目录的绝对路径，其中构建缓存将存储在选定的执行程序(本地、Docker、SSH)的上下文中。如果使用docker executor，则需要在其卷参数中包含此目录。 |
　　　　| environment | 追加或覆盖环境变量 |
　　　　| request_concurrency | 限制GitLab对新作业的并发请求数量(默认1) |
　　　　| output_limit | 设置最大构建日志大小(以kb为单位)，默认设置为4096 (4MB) |
　　　　| pre_clone_script | 在克隆Git存储库之前要在Runner上执行的命令。例如，这可以首先用于调整Git客户机配置。要插入多个命令，请使用(三引号)多行字符串或“ ”字符。 |
　　　　| pre_build_script | 在克隆Git存储库之后，但在执行构建之前，要在Runner上执行的命令。要插入多个命令，请使用(三引号)多行字符串或“ ”字符。 |
　　　　| post_build_script | 要在Runner上执行的命令在执行构建之后，但在执行after_script之前执行。要插入多个命令，请使用(三引号)多行字符串或“ ”字符。 |
　　　　| clone_url | 覆盖GitLab实例的URL。如果Runner无法在URL GitLab上连接到GitLab，则使用GitLab。 |
　　　　| debug_trace_disabled | 禁用CI_DEBUG_TRACE特性。当设置为true时，即使用户将CI_DEBUG_TRACE设置为true，调试日志(跟踪)也将保持禁用状态。 |
　　　　| referees | 额外的工作(job)监视工作者(workers)，将他们的结果作为工作工件传递给GitLab |　　　　　　　

2、使用docker安装查看runner配置

　　$ cat /data/etc/gitlab-runner/config.toml (具体路径依docker run而定)

　　　　[runners.docker]
　　　　| host | 指定自定义Docker端点，默认使用`DOCKER_HOST`环境或 unix:///var/run/docker.sock |
　　　　| hostname | 为Docker容器指定自定义主机名 |
　　　　| runtime | 为Docker容器指定一个运行时 |
　　　　| tls_cert_path | 设置时将使用ca.pem、cert.pem和key。从该文件夹中的pem建立到Docker的安全TLS连接(在boot2docker中非常有用) |
　　　　| tls_verify | 启用或禁用连接到Docker守护进程的TLS验证。默认情况下禁用。 |
　　　　| image | 使用此映像运行构建 |
　　　　| memory | 包含内存限制的字符串值 |
　　　　| memory_swap | 包含总内存限制的字符串值 |
　　　　| memory_reservation | 包含内存软限制的字符串值 |
　　　　| oom_kill_disable | 如果发生内存不足(OOM)错误，不要杀死容器中的进程 |
　　　　| oom_score_adjust | OOM分数调整，正意味着杀得早 |
　　　　| cpuset_cpus | 包含要使用的cgroups cpusetcpu的字符串值 |
　　　　| cpu_shares | 用于设置相对CPU使用量的CPU共享数量，默认为1024 |
　　　　| cpus | cpu数量的字符串值(在docker 1.13或更高版本中可用) |
　　　　| dns | 容器要使用的DNS服务器的列表 |
　　　　| dns_search | DNS搜索域的列表 |
　　　　| privileged | 使容器以特权模式运行(不安全) |
　　　　| disable_entrypoint_overwrite | 禁用映像 entrypoint 覆盖 |
　　　　| userns_mode | 当启用usernamespace重新映射选项时，为容器设置usernamespace模式。(可在docker1.10或更高版本中获得) |
　　　　| cap_add | 向容器添加额外的Linux功能 |
　　　　| cap_drop | 从容器中删除额外的Linux功能 |
　　　　| security_opt | 设置安全选项(-security-opt in docker run)，获取‘:‘分隔键/值的列表 |
　　　　| devices | 与容器共享其他主机设备 |
　　　　| cache_dir | 指定Docker缓存应该存储在哪里(可以是绝对的，也可以是相对于当前工作目录的)。有关更多信息，请参见disable_cache。 |
　　　　| disable_cache | Docker执行器有两层缓存:全局缓存(与任何其他执行器一样)和基于Docker卷的本地缓存。此配置标志仅作用于禁止使用自动创建(未映射到主机目录)缓存卷的本地缓存卷。换句话说，它只阻止创建保存构建的临时文件的容器，如果运行器配置为分布式缓存模式，它不会禁用缓存。 |
　　　　| network_mode | 将容器添加到自定义网络 |
　　　　| wait_for_services_timeout | 指定等待docker服务的时间，设置为0禁用，默认为30 |
　　　　| volumes | 指定应该挂载的其他卷(与Docker的-v标志相同的语法) |
　　　　| extra_hosts | 指定应该在容器环境中定义的主机 |
　　　　| shm_size | 为映像指定共享内存大小(以字节为单位) |
　　　　| volumes_from | 以`<container name>[:<ro|rw>]`的形式指定要从另一个容器继承的卷的列表。访问级别默认为读写，但可以手动设置为ro(只读)或rw(读写)。 |
　　　　| volume_driver | 指定容器使用的卷驱动程序 |
　　　　| links | 指定应该与构建容器链接的容器 |
　　　　| allowed_images | 指定可以在.gitlab-ci.yml中指定的图像的通配符列表。如果不提供所有映像，则允许(相当于`["*/*:*"]`) |
　　　　| allowed_services | 指定可以在.gitlab-ci.yml中指定的通配符服务列表。如果不提供所有映像，则允许(相当于`["*/*:*"]`) |
　　　　| pull_policy | 指定映像拉取策略:`never`，`if-not-present`或 `always`(默认);请参阅pull策略文档 |
　　　　| sysctls | 指定sysctl选项 |
　　　　| helper_image | (高级)覆盖用于克隆repos和上传工件的默认 `helper 映像` |

示例：

　　[runners.docker]
　　host = ""
　　hostname = ""
　　tls_cert_path = "/Users/ayufan/.boot2docker/certs"
　　image = "ruby:2.6"
　　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.services]]
　　name = "mysql"
　　alias = "db"
　　[[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"

（以下是其他可用区段定义）

3、 [runners.ssh] 区段

| Parameter | Description |
| ------------ | ------------ |
| host | 连接到哪里(使用docker-ssh时被覆盖) |
| port | 指定端口，默认值:22 |
| user | 指定用户 |
| password | 指定密码 |
| identity_file | 指定SSH私有密钥的文件路径(id_rsa、id_dsa或id_edcsa)。文件需要不加密地存储 |

//示例
```bash
[runners.ssh]
host = "my-production-server"
port = "22"
user = "root"
password = "production-server-password"
identity_file = ""
```

4、 [runners.cache] 区段

GitLab Runner 1.1.0 中引入。

| Parameter | Type | Description |
| ------------ | ------------ | ------------ |
| Type | string | s3 或 gcs |
| Path | string | 添加到缓存URL前的路径的名称。 |
| Shared | boolean | 启用运行程序之间的缓存共享，默认为false。 |

##### （1）[runners.cache.s3]

允许配置S3存储用于缓存。本节包含与S3相关的设置，这些设置以前在该[runners.cache]节中全局存在。

//示例
```bash
[runners.cache]
Type = "s3"
Path = "path/to/prefix"
Shared = false
[runners.cache.s3]
ServerAddress = "s3.amazonaws.com"
AccessKey = "AMAZON_S3_ACCESS_KEY"
SecretKey = "AMAZON_S3_SECRET_KEY"
BucketName = "runners-cache"
BucketLocation = "eu-west-1"
Insecure = false
```

参考：https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscaches3-section

5、[runners.kubernetes] 区段

GitLab Runner v1.6.0 中添加

| Parameter | Type | Description |
| ------------ | ------------ | ------------ |
| host | string | 可选的Kubernetes主机URL(如果未指定，将尝试自动发现) |
| cert_file | string | 可选的Kubernetes认证证书 |
| key_file | string | 可选的Kubernetes主认证私钥 |
| ca_file | string | 可选的Kubernetes主认证证书 |
| image | string | 默认的docker镜像，当没有指定时用于构建 |
| namespace | string | 命名空间来运行Kubernetes作业 |
| privileged | boolean | 运行所有启用了特权标志的容器 |
| node_selector | table | 一个table的key=value对string=string。设置此限制将Pod的创建限制为与所有key=value对匹配的Kubernetes节点 |
| image_pull_secrets | array | 用于验证docker映像提取的秘密列表 |

//示例
```bash
[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
image_pull_secrets = ["docker-registry-credentials"]
[runners.kubernetes.node_selector]
gitlab = "true"
```

更多参考：https://docs.gitlab.com/runner/executors/kubernetes.html

6、Helper image

当使用docker、docker+machine或kubernetes执行器之一时，GitLab Runner使用特定的容器来处理Git、工件和缓存操作。这个容器是由一个名为helper映像的特殊映像创建的。

helper 映像基于Alpine Linux，它提供amd64和arm架构。它包含一个`gitLab-run-helper`二进制文件，这是GitLab Runner二进制文件的特殊编译，只包含可用命令的一个子集，以及Git、Git LFS、SSL证书存储和Alpine的基本配置。

当从DEB/RPM包中安装GitLab Runner时，两个映像(amd64和基于arm的)都安装在主机上。当运行器为作业执行准备好环境时，如果在Docker引擎上没有找到指定版本(基于Runner的Git修订版)中的映像，则会自动加载它。它对docker和docker+machine执行器都是这样工作的。

对于kubernetes executor或手动安装GitLab Runner时，情况略有不同。对于手动安装，gitlab-runner-helper二进制文件不包括在其中，对于kubernetes executor, kubernetes的API不允许从本地存档加载gitlab-runner-helper映像。在这两种情况下，GitLab Runner都将从Docker Hub (GitLab的官方存储库GitLab / GitLab -run -helper)下载帮助器映像，方法是使用Runner的修订和架构来定义应该下载哪个标记

6.1 覆盖 helper image

在某些情况下，您可能需要覆盖帮助器映像。这样做的原因有很多:

（1）加快作业执行: 在internet连接速度较慢的环境中，从Docker Hub一次又一次地下载相同的映像可能会显著增加作业的时间。从本地注册表(其中存储 gitlab/gitlab-runner-helper:XYZ 的精确副本)下载帮助程序映像可能会加快速度。

（2）安全考虑：许多人不喜欢下载以前没有检查过的外部依赖项。可能有一个业务规则只使用被审查并存储在本地存储库中的依赖项。

（3）构建没有internet访问的环境：在某些情况下，作业是在一个具有专用的、封闭的网络的环境中执行的(这不适用于kubernetes执行程序，因为映像仍然需要从外部注册中心下载，至少kubernetes集群可以从外部注册中心下载映像)。

（4）额外的软件：有些用户可能希望在帮助映像中安装一些额外的软件，比如openssh，以支持通过git+ssh而不是git+http访问的子模块。

在上面描述的任何情况下，都可以使用helper_image配置字段来配置自定义映像，该字段可用于docker、docker+machine和kubernetes执行器:

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

请注意，助手映像的版本应该与GitLab Runner的版本严格耦合。就像上面所描述的那样,提供这样的的一个主要原因是 Runner 使用gitlab-runner-helper二进制图像,这编译二进制GitLab runner的一部分来源是使用一个内部API,预计在二进制文件都是相同的。

Runner 默认引用 gitlab/gitlab-run-helper:XYZ 映像，其中XYZ基于运行器的体系结构和Git修订。从GitLab Runner 11.3开始，通过使用版本变量之一，可以自动定义使用过的图像的版本:

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