跳转到内容
免费试用 Gitea Cloud ☁️ 30 天,加速你的开发与部署!
技术支持

配置

本页的选项对两种后端都适用。示例中写在 runtime 下的选项,使用 Kubernetes 后端时请改写在 kubernetesRuntime 下。仅属于某个后端的选项在其页面中介绍:Docker-in-Docker 与 Kubernetes。存储与缓存见存储与缓存。

gitea:
instanceUrl: "https://gitea.example.com"

instanceUrl 是 controller 与 runner 访问 Gitea 所用的地址。它可以是集群内的地址,例如部署在集群中的 Gitea 的 Service;若 Gitea 部署在某个路径下,地址须包含该路径。任务检出代码、上传产物时使用的是 Gitea 自身配置的地址(其 ROOT_URL),因此任务容器也须能访问该地址。

将注册令牌保存在 Runner 所在命名空间的 Secret 中,并在 registrationTokenSecretRef 中引用它:

Terminal window
kubectl -n <namespace> create secret generic runner-registration-token \
--from-literal=token=<registration token>
gitea:
registrationTokenSecretRef:
name: runner-registration-token
key: token
  • 只有 controller 使用该令牌。runner Pod 获取的是自己 runner 的凭证,而不是令牌。
  • 值不能带首尾空白,而文件以换行结尾时,--from-file 会将该换行一并写入。controller 会拒绝这样的值,并报告 RegistrationTokenUnavailable 警告事件。在 YAML 清单中,请在 stringData 下把令牌写在一行内。
  • 不建议使用 gitea.registrationToken 以明文将令牌写在 Runner 中:任何能读取该 Runner 的人都能读取到令牌。请改用 registrationTokenSecretRef。两者只能设置其一。

轮换令牌:Secret 的值变更后,每个 runner 都会用新令牌重新注册,其 Pod 随之重建,见配置变更如何生效。缓存卷会保留。原有的注册在 Gitea 中会成为离线 runner,可在 Gitea 的 runner 页面删除。

若 Gitea 使用自签名证书或内部 CA 签发的证书,须关闭证书校验,否则 controller 与 runner 都无法连接:

gitea:
skipTlsVerify: true # 默认 false

目前还无法为 controller 提供 CA 证书,只能通过 skipTlsVerify: true 解决。后续版本将支持提供 CA。

skipTlsVerify 作用于 controller 与 runner,但不作用于任务。任务容器会自行校验证书,例如 actions/checkout 克隆仓库时,因此任务镜像须信任 Gitea 的证书,否则任务会失败。对于 runner 访问的其他服务,如内部镜像仓库或 action 仓库,若要信任其 CA 而不是跳过校验,见 init container 中的示例。

scalability:
minSize: 1 # 没有任务排队时保留的 runner Pod 数,默认 0
maxSize: 10 # 默认 10
cpuRequest: "2"
memoryRequest: 4Gi
# cpuLimit: "4" # 不设置则没有上限
# memoryLimit: 8Gi
  • minSize 是 runner Pod 数量的下限,不区分繁忙或空闲。minSize: 0 时,空闲后所有 runner Pod 都会被回收,下一个任务需要等待完整的启动过程:可能包括新建节点、拉取镜像和注册,通常需要几分钟。若需避免这段等待,请至少保留一个 runner。所有 runner Pod 都在执行任务时,新任务仍需等待新的 runner Pod。
  • 资源设置在 Docker-in-Docker 后端中作用于每个 runner Pod,在 Kubernetes 后端中作用于每个 job Pod 的 job 容器,见并发与伸缩。

runner Pod 数量随队列变化的方式:

  • 扩容:有任务排队时,controller 一次性为空闲 runner 无法承接的任务增加 runner Pod。例如有 2 个空闲 runner、5 个排队任务时,增加 3 个 runner Pod。Kubernetes 后端见并发与伸缩。
  • 缩容:没有任务排队时,从编号最大的开始,一次回收一个 runner Pod,前提是该 runner 已空闲约 5 分钟。因此从满负载回到 minSize 需要一段时间。编号最大的 runner 繁忙时,即使其他 runner 空闲,也不会回收任何 runner Pod。
  • 减小 maxSize 会立即回收超出新上限的 runner Pod,无论它们是否在执行任务:其任务有 runner 的 shutdownTimeout 时长用于收尾。它们的存储卷与注册信息也会立即删除,而不是保留 storage.cacheTTL。
  • 修改 minSize 或 maxSize 会立即生效,不会重建其他 runner Pod。

当前的目标数量记录在 Runner 的 status 中,每次变化都会产生 ScaleUp 或 ScaleDown 事件:

Terminal window
kubectl -n <namespace> get runner <name> -o jsonpath='{.status.targetSize}'
kubectl -n <namespace> describe runner <name>

Runner 的 label 是任务在 runs-on 中选择的名称,每个 label 对应任务运行所用的镜像。label 没有默认值:每个 Runner 至少要列出一个。

runtime:
labels:
ubuntu-latest: docker://docker.gitea.com/runner-images:ubuntu-latest # Docker-in-Docker
kubernetesRuntime:
labels:
ubuntu-latest: docker.gitea.com/runner-images:ubuntu-latest # Kubernetes,不带前缀

使用 Docker-in-Docker 后端时,label 的值也可以是 host:其任务以 host 方式运行,即直接在 runner 容器内运行,而不是在 runner 为任务单独创建的任务容器中运行。但工作流为任务指定了 container 时,该任务仍在任务容器中运行。

只要任务 runs-on 中的任一 label 是 Runner 的 label,controller 就会将该排队任务计入,即使该任务还需要 Runner 没有的 label、因而无法运行它。因此,令牌覆盖相同仓库的两个 Runner 不应使用相同的 label:否则一个排队的任务会让两者都扩容,而只有其中一个能执行它。

controller 之外的 runner(例如手动注册的)使用相同的 label 时同理:controller 不把它们计为空闲容量,可能扩容出用不上的 runner Pod,且同一 label 的任务会落在不同的环境中。

envs 为 Runner 的每个任务设置环境变量:

runtime:
envs:
- name: NPM_CONFIG_REGISTRY
value: "https://npm.example.com/"

这些变量不会设置在 runner 容器中。runner 和 Docker 需要的变量,如代理,请写在 runnerEnv 中。

这些变量由 controller 写入 runner 配置文件,runner 执行每个任务时将其设置到任务中。runner 启动时会先将其 value 中的 ${NAME} 替换为 runner 容器自身的环境变量 NAME(例如通过 runnerEnv 设置的变量),该变量未设置时 runner 无法启动。字面量 ${NAME} 须写作 $${NAME}。

runnerEnv 与 runnerEnvFrom 设置 runner 容器自身的环境变量,写法与 Kubernetes 容器的 env 和 envFrom 相同。使用 Docker-in-Docker 后端时,Docker daemon 运行在同一容器中,也会获得这些变量。

runtime:
runnerEnv:
- name: HTTPS_PROXY
value: "http://proxy.example.com:8080"
- name: NO_PROXY
value: "gitea.example.com,.svc.cluster.local"
- name: NPM_TOKEN
valueFrom:
secretKeyRef:
name: runner-secrets
key: npm-token
runnerEnvFrom:
- configMapRef:
name: runner-env
  • 引用的 Secret 与 ConfigMap 须位于 Runner 所在的命名空间。其中某个对象或键不存在、且未标记 optional: true 时,controller 不创建 runner Pod,并报告 BuildRunnerWorkerFailed 警告事件。
  • 被引用的 Secret 或 ConfigMap 有任何变更(包括只改了其标签或注解),都会重建 runner Pod,见配置变更如何生效。
  • 同名变量以 runnerEnv 中的为准。
  • GITEA_INSTANCE_URL、CONFIG_FILE、RUNNER_STATE_FILE、GITEA_RUNNER_LABELS 与 GITEA_RUNNER_ONCE,以及 Kubernetes 后端的 POD_IP,均为保留变量:其中一些由 controller 自行设置,其余的会改变 runner 的注册或接取任务的方式。在 runnerEnv 中设置它们的 Runner 会被拒绝。runnerEnvFrom 的来源中含有这些变量(计入 prefix)时,controller 不创建 runner Pod。
  • 以 host 方式运行的任务可以读取这些变量。在单独的任务容器中运行的任务无法读取,代理变量除外,见下文。

在 runner 容器上设置 HTTP_PROXY、HTTPS_PROXY 与 NO_PROXY 后,以下流量经过代理:

  • runner 到 Gitea、action 仓库,以及缓存服务器或 S3 存储桶的连接;
  • 使用 Docker-in-Docker 后端时,Docker daemon 拉取镜像,除非其 daemon.json 设置了 proxies;
  • 任务、服务与镜像构建:runner 会把这些变量传给它们,并将缓存服务器和服务加入其 NO_PROXY。envs 中设置的代理变量优先。

NO_PROXY 须列出 runner 直接访问的集群内与内网地址,否则这些请求也会发往代理:

地址 NO_PROXY 中遗漏时
Gitea runner 无法上线
内置缓存服务器(.svc.cluster.local,或 cacheServer.host)、外部缓存服务器或 S3 endpoint 工作流缓存失效,但任务不会失败
内部镜像仓库 无法拉取任务镜像
Kubernetes 后端:API Server,即 runner Pod 中 KUBERNETES_SERVICE_HOST 的 IP 或其所在网段 无法创建 job Pod,任务失败

envs 中的 ${NAME} 可以把 runner 容器的变量传给任务,其值既不会出现在 Runner 中,也不会出现在生成的配置文件中:

runtime:
runnerEnv:
- name: NPM_TOKEN
valueFrom:
secretKeyRef:
name: runner-secrets
key: npm-token
envs:
- name: NPM_TOKEN
value: "${NPM_TOKEN}"

以这种方式传递的值不会在任务日志中被遮蔽。需要在日志中遮蔽,或只允许部分仓库使用的值,请使用 Gitea Actions 的密钥(secrets)。

runnerInitContainers 为 runner Pod 添加 init container,它们在 runner 启动前依次运行,例如为 runner 准备文件。文件通过 emptyDirMounts 中的目录传递给 runner:runner 容器在其 mountPath 处挂载该目录,init container 按其 volumeName 挂载。

以下示例将 ConfigMap 中的内部 CA 证书与镜像自带的证书合并,使 runner 能访问使用该 CA 证书的服务,如内部的 action 仓库。runner 从 SSL_CERT_FILE 读取证书,它在部分下载中使用的 git 则从 GIT_SSL_CAINFO 读取:

runtime:
configMapMounts:
- volumeName: company-ca
configMapName: company-ca # 证书以 *.crt 保存
mountPath: /etc/company-ca
readOnly: true
emptyDirMounts:
- volumeName: ca-bundle
mountPath: /etc/ca-bundle
readOnly: true
runnerInitContainers:
- name: ca-bundle # 不写 image:使用 runner 镜像
command: ["sh", "-c", "cat /etc/ssl/certs/ca-certificates.crt /in/*.crt > /out/ca-certificates.crt"]
volumeMounts:
- name: company-ca
mountPath: /in
readOnly: true
- name: ca-bundle
mountPath: /out
runnerEnv:
- name: SSL_CERT_FILE
value: /etc/ca-bundle/ca-certificates.crt
- name: GIT_SSL_CAINFO
value: /etc/ca-bundle/ca-certificates.crt
  • init container 的写法与 Kubernetes 容器相同,但只支持以下字段:name、image、imagePullPolicy、command、args、workingDir、env、envFrom、resources、securityContext 与 volumeMounts。不支持 sidecar(restartPolicy)和探针。名称 install-registration、chown-cache 与 runner 已被 controller 占用。
  • 它们在 controller 自身的 init container 之后运行。不写 image 时使用 runner 镜像及其 imagePullPolicy,不写 resources 时使用 runner 容器的资源设置。
  • 它们可以挂载 configMapMounts、secretMounts 与 emptyDirMounts 的卷,使用 Docker-in-Docker 后端时还可以挂载 pvcMounts 的卷。
  • 它们不挂载 ServiceAccount 令牌,因此无法使用 Kubernetes API。
  • 使用 Kubernetes 后端时,它们须满足 Pod Security 的 restricted 级别:不能以 root 运行,不能使用特权模式或提权,capabilities 不能超出 NET_BIND_SERVICE。未设置的 allowPrivilegeEscalation 与 capabilities.drop 默认为 false 与 ["ALL"]。不满足时,Runner 会被拒绝,或 controller 不创建 runner Pod 并报告 BuildRunnerWorkerFailed 警告事件。Docker-in-Docker 后端没有这一限制。
  • 某个 init container 以错误退出或无法启动(例如无法拉取其镜像)时,runner 不会启动,kubelet 会不断重试,controller 报告 RunnerInitContainerFailed 警告事件,附带退出码与日志末尾。
  • 它们须在 15 分钟内完成:runner Pod 启动 15 分钟后(计入拉取镜像与 init container 的时间),其 runner 仍未在 Gitea 上线时,该 Pod 会被删除并重新创建,见未能上线的 runner Pod。init container 持续失败时也是如此。
  • 修改 runnerInitContainers,或其 env、envFrom 读取的 Secret 或 ConfigMap 发生变更,都会重建 runner Pod。挂载的 ConfigMap 或 Secret 的内容变更则不会。

除了 Docker-in-Docker 后端的 pvcMounts,还可以向 runner 容器挂载以下三类卷:

runtime:
configMapMounts:
- volumeName: extra-config
configMapName: runner-extra-config
mountPath: /etc/runner-extra
readOnly: true
secretMounts:
- volumeName: extra-secret
secretName: runner-extra-secret
mountPath: /etc/runner-secret
readOnly: true
emptyDirMounts:
- volumeName: prepared
mountPath: /etc/prepared
medium: Memory # 留空为节点磁盘;Memory 计入 Pod 的内存
sizeLimit: 64Mi # 超出时 Pod 会被驱逐
  • configMapMounts 与 secretMounts 还支持 items、defaultMode 与 optional,与 Pod 的卷相同。

  • 每个挂载的 volumeName 须唯一,且不能使用以下名称。这些名称由 controller 为自己的卷保留,无论 Runner 当前是否用到这些卷:

    • runner-config
    • runner-data
    • runner-registration
    • runner-cache
    • runner-action-cache
    • cache-server-secret
    • cache-s3-credentials
    • runner-job-tmpfs
    • no-service-account-token

    否则 controller 不创建 runner Pod,并报告指明该卷的 BuildRunnerWorkerFailed 警告事件,正在运行的 runner Pod 保持不变。

  • configMapMounts、secretMounts 与 emptyDirMounts 的卷挂载到 runner 容器中,而不是任务容器中。

runner Pod 的配置变更时会重建,包括:镜像、label、环境变量、init container 等 runner Pod 的选项,runnerEnv、runnerEnvFrom 或 init container 环境变量读取的 Secret 或 ConfigMap,轮换注册令牌、缓存服务器密钥或 S3 密钥,以及缓存卷达到 storage.cacheMaxAge。重建不会中断任务:

  • 没有在执行任务的 runner Pod 立即重建。
  • Docker-in-Docker 后端:正在执行任务的 runner Pod 在任务结束后重建,期间会有 RollDeferred 事件。
  • Kubernetes 后端:正在执行任务的 runner Pod 会被排空:不再接取新任务,当前的任务完成后重建。同一 Runner 同一时间只排空一个 runner Pod,其他 runner Pod 承接排队的任务,必要时扩容。等待期间的事件为 RollDeferred,开始排空时为 DrainWorker。

内置缓存服务器的配置变更时会立即重建,见内置缓存服务器。

nodeSelector:
node-pool: runners
tolerations:
- key: dedicated
operator: Equal
value: runner
effect: NoSchedule
affinity: {} # 标准的 Kubernetes affinity
imagePullSecrets:
- name: <registry credentials>

这些字段位于 spec 顶层,而不是 runtime 下。若要让一组节点专供 runner 使用,请为这些节点设置 taint,以阻止其他 Pod 调度到这些节点,并在 tolerations 中容忍该 taint:

  • tolerations 与 imagePullSecrets 同样作用于内置缓存服务器。它不使用 nodeSelector 或 affinity,可以运行在任何能访问其存储卷的节点上。
  • 这些节点上的 DaemonSet,尤其是存储驱动的节点插件,也须容忍该 taint,否则 runner Pod 的存储卷无法挂载。
  • runner Pod 与内置缓存服务器带有注解 karpenter.sh/do-not-disrupt: "true",Karpenter 不会为整合节点而回收它们所在的节点。因此 minSize 保留的 runner 所在的节点会一直保留。
  • 使用 Kubernetes 后端时,这些字段只作用于 runner Pod。job Pod 的这些设置来自 job Pod 模板。
  • 修改这些字段会按配置变更如何生效重建 runner Pod,并立即重建内置缓存服务器。

controller 根据 Runner 生成 runner 的配置文件(config.yaml)。若要自行编写,请将其放在 Runner 所在命名空间的 ConfigMap 中,键为 config.yaml,并在 runnerConfigMapName 中指定该 ConfigMap:

runtime:
runnerConfigMapName: my-runner-config

此时 controller 原样挂载该文件,并且:

  • 不再向其中写入原本会写入的选项:labels 中的镜像、envs、jobTmpfs.tmpSize、缓存设置,以及 pvcMounts 的 container.valid_volumes;

  • 不创建内置缓存服务器,请在文件中自行配置缓存;

  • 仍会依据部分选项工作,因此文件须与它们保持一致:

    controller 依据 用于 文件中须保持一致
    labels 的名称 统计排队任务 runner.labels 中相同的名称,runner 按它接取任务
    shutdownTimeout 设置 terminationGracePeriodSeconds runner.shutdown_timeout 中相同的值
    gitea.skipTlsVerify 连接 Gitea runner.insecure 中相同的值
    每个 runner Pod 一个任务(Docker-in-Docker) 规划伸缩 runner.capacity: 1。Kubernetes 后端见该页

编写该文件时:

  • 设置 host.workdir_parent: /cache/act_workdir,与生成的配置文件相同,使下载的 action 保存在 action 缓存卷上。
  • 不要设置 runner.file:controller 会自行放置 runner 的注册信息。

使用 Kubernetes 后端时,另见该页的使用自定义 runner 配置文件。配置文件中各项的说明见 runner 的 config.example.yaml。