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

Runner 字段参考

本页列出 Runner 资源(apiVersion: gitea.com/v1,kind: Runner)的所有字段及其默认值。以下代码块仅供查阅,不是可直接应用的清单:部分字段互斥,例如 runtime 与 kubernetesRuntime。

必填项:

  • gitea.instanceUrl
  • gitea.registrationTokenSecretRef 与 gitea.registrationToken 之一
  • runtime 与 kubernetesRuntime 之一,及其 labels

其余字段都有默认值或可以省略。kubectl explain runner.spec 可以从集群中查看相同的字段。

spec:
gitea:
instanceUrl: "https://<gitea host>" # 必填
registrationTokenSecretRef: # 从 Runner 所在命名空间的 Secret 中读取令牌;与 registrationToken 须设置且只能设置其一
name: runner-registration-token
key: token
registrationToken: "<token>" # 不建议使用:以明文写入令牌,请改用 registrationTokenSecretRef
skipTlsVerify: false # 自签名证书时设为 true,作用于 controller 与 runner

见 Gitea 地址、注册令牌与自签名证书。

Docker-in-Docker 后端。runtime 与 kubernetesRuntime 须设置且只能设置其一。

spec:
runtime:
image: gitea/runner:nightly-dind # -dind 版本,5.3.0 及以上;请固定版本号
imagePullPolicy: IfNotPresent # Always、IfNotPresent 或 Never;不设置时使用 kubelet 的默认行为
labels: # 必填,至少一项,无默认值;runs-on 名称: docker://<任务镜像>,或 host
ubuntu-latest: docker://docker.gitea.com/runner-images:ubuntu-latest
envs: # 每个任务的环境变量
- name: NPM_CONFIG_REGISTRY
value: "https://npm.example.com/"
runnerEnv: [] # runner 容器的环境变量,写法同容器的 env;最多 256 项
runnerEnvFrom: [] # 写法同容器的 envFrom
shutdownTimeout: 10m # runner 停止时等待其任务的时长
terminationGracePeriodSeconds: 900 # 不设置时为 shutdownTimeout + 5m
runAsUser: 1000 # 用于 -dind-rootless 镜像,须配合 storage.dockerStorageMountPath
jobTmpfs: # 将任务工作区与 /tmp 放在内存中
workspaceSize: 8Gi # 必填
tmpSize: 2Gi # 可选;使用 runnerConfigMapName 时不生效
pvcMounts: # Runner 所在命名空间中已有的 PVC
- volumeName: shared-data # 必填
claimName: my-existing-pvc # 必填
mountPath: /mnt/shared # 必填,绝对路径
readOnly: true # 默认 true
configMapMounts:
- volumeName: extra-config
configMapName: runner-extra-config
mountPath: /etc/runner-extra
readOnly: true
items: [] # 可选,要投射的键
defaultMode: 420
optional: false
secretMounts:
- volumeName: extra-secret
secretName: runner-extra-secret # 必填
mountPath: /etc/runner-secret
readOnly: true
items: []
defaultMode: 420
optional: false
emptyDirMounts: # 空目录,init container 可向其中写入
- volumeName: prepared # 必填
mountPath: /etc/prepared # 必填,绝对路径
readOnly: true
medium: "" # "" 为节点磁盘,或 Memory
sizeLimit: 64Mi # 可选;超出时 Pod 会被驱逐
runnerInitContainers: # 最多 16 个,在 runner 之前运行
- name: prepare # 必填;不能为 install-registration、chown-cache 或 runner
image: "" # 留空时使用 runner 镜像
imagePullPolicy: IfNotPresent # image 留空时沿用 runner 镜像的策略
command: ["sh", "-c", "..."]
args: []
workingDir: ""
env: []
envFrom: []
resources: {} # 不设置时与 runner 容器相同
securityContext: {}
volumeMounts: # 按 volumeName 挂载上述四类挂载中的卷
- name: prepared
mountPath: /out
runnerConfigMapName: "" # 含 config.yaml 的 ConfigMap,替代生成的配置文件
  • 每个挂载的 volumeName 须唯一,且不能与 controller 使用的名称相同,见其他挂载。
  • runnerEnv 不能设置 GITEA_INSTANCE_URL、CONFIG_FILE、RUNNER_STATE_FILE、GITEA_RUNNER_LABELS 或 GITEA_RUNNER_ONCE。
  • label 的值不能以 kubernetes: 开头,这种情况请使用 kubernetesRuntime。

Kubernetes 后端。不能与 runtime 同时设置。

spec:
kubernetesRuntime:
image: gitea/runner:nightly # 不带 -dind 的版本,5.3.0 及以上;请固定版本号
imagePullPolicy: IfNotPresent
capacity: 4 # 每个 runner Pod 的任务数,至少 1
labels: # 必填,1 到 64 项,无默认值;runs-on 名称: 任务镜像,不带 scheme
ubuntu-latest: docker.gitea.com/runner-images:ubuntu-latest
jobPodTemplate: {} # 所有 job Pod 的基础:只能包含 metadata 与 spec
jobPodTemplates: {} # 以 label 名称为键,叠加在 jobPodTemplate 之上;最多 64 项
runnerServiceAccountName: "" # 留空时由 controller 创建 <name>-worker
runnerRunAsUser: 1000 # runner Pod 的 UID、GID 与 fsGroup,不能为 0
runnerResources: # runner 容器的资源
requests:
cpu: 100m
memory: 256Mi
envs: [] # 同 runtime
runnerEnv: [] # 同 runtime;另外不能设置 POD_IP
runnerEnvFrom: []
shutdownTimeout: 3h # runner 停止或排空时等待其任务的时长
terminationGracePeriodSeconds: 11100 # 不设置时为 shutdownTimeout + 5m
configMapMounts: [] # 同 runtime
secretMounts: []
emptyDirMounts: []
runnerInitContainers: [] # 同 runtime,但须满足 Pod Security 的 restricted 级别
runnerConfigMapName: "" # label 须为 <name>:kubernetes://<image> 的形式
  • label 名称最长 255 个字符,不能包含 :、, 或空白字符。镜像不能包含 ://。
  • 该后端没有 pvcMounts、runAsUser 与 jobTmpfs。
spec:
scalability:
minSize: 0 # 没有任务排队时保留的 runner Pod 数,0 到 9999
maxSize: 10 # 1 到 9999,不小于 minSize
cpuRequest: "2" # 每个 runner Pod(Docker-in-Docker)或 job 容器(Kubernetes)
memoryRequest: 4Gi
cpuLimit: "4" # 不设置则没有上限
memoryLimit: 8Gi # 不设置则没有上限

见伸缩。

spec:
storage:
className: standard # 默认的 StorageClass,也是缓存服务器存储卷的 StorageClass
dockerStorageClassName: "" # Docker 数据目录;留空时使用 className
actionCacheClassName: "" # action 缓存;留空时使用 className
cacheVolumeSize: 100Gi # Docker 数据目录,每个 runner Pod 一个(仅 Docker-in-Docker)
actionCacheVolumeSize: 10Gi # action 缓存,每个 runner Pod 一个
cacheServerVolumeSize: 500Gi # 内置缓存服务器
dockerStorageMountPath: /var/lib/docker # Docker daemon 的数据目录;rootless 镜像须修改
cacheTTL: 168h # 存储卷在最后一次使用后保留的时长
cacheMaxAge: 720h # runner Pod 的存储卷自创建起达到该时长后重建
allowDeleteCachePVC: false # 允许为更换 StorageClass 或缩小容量而重建存储卷
reclaimPolicy: Delete # Delete 或 Retain;不设置时沿用 StorageClass 的策略

dataVolumeSize 已弃用,不再生效。见存储与缓存。

工作流缓存有三种方式,同时只有一种生效:

  • S3 兼容存储(推荐):设置 s3。
  • 外部缓存服务器:设置 externalServerURL 与 externalSecretRef。
  • 内置缓存服务器:以上都不设置时使用,可通过 host、port 调整。

s3 与 externalServerURL 不能同时设置,未使用的方式的字段会被忽略。

spec:
cacheServer:
host: "" # 内置缓存服务器:留空时为 <name>-cache-server-svc.<namespace>.svc.cluster.local
port: 80 # 内置缓存服务器:80;使用 kubernetesRuntime 时为 8080,且须不低于 1024
externalServerURL: "" # 使用自己的缓存服务器,替代内置的
externalSecretRef: # 从 Secret 中读取其密钥
name: cache-server-secret
key: secret
externalSecret: "" # 已弃用:以明文提供密钥;不能与 externalSecretRef 同时设置
s3: # 将缓存存放在存储桶中,不使用缓存服务器;不能与 externalServerURL 同时设置
endpoint: "https://s3.us-west-2.amazonaws.com" # 必填,http:// 或 https://
region: "us-west-2" # 必填
bucket: "runner-cache" # 必填
prefix: "" # 留空时为 Runner 的 <namespace>/<name>
pathStyle: true # 不设置时由 runner 决定
accessKeyRef: # 必填
name: runner-cache-s3
key: access-key
secretKeyRef: # 必填
name: runner-cache-s3
key: secret-key

见工作流缓存。使用 runnerConfigMapName 时,整个部分都不生效。

spec:
nodeSelector: {} # runner Pod
affinity: {} # runner Pod
tolerations: [] # runner Pod 与内置缓存服务器
imagePullSecrets: [] # runner Pod 与内置缓存服务器;不用于 Docker-in-Docker 的任务镜像

使用 Kubernetes 后端时,job Pod 的这些设置来自 kubernetesRuntime.jobPodTemplate。见调度。

字段 说明
targetSize controller 当前期望的 runner Pod 数量
targetSizeUpdatedAt targetSize 最后一次变化的时间