Runner Reference
This page lists every field of the Runner resource (apiVersion: gitea.com/v1, kind: Runner) with its default. The blocks below are a reference, not a manifest to apply: some fields exclude others, such as runtime and kubernetesRuntime.
Required fields:
gitea.instanceUrl- One of
gitea.registrationTokenSecretRefandgitea.registrationToken - One of
runtimeandkubernetesRuntime, with itslabels
Everything else has a default or can be left out. kubectl explain runner.spec shows the same fields from the cluster.
spec: gitea: instanceUrl: "https://<gitea host>" # required registrationTokenSecretRef: # the token from a Secret in the namespace of the Runner; exactly one of this and registrationToken name: runner-registration-token key: token registrationToken: "<token>" # not recommended: the token as plain text; use registrationTokenSecretRef skipTlsVerify: false # true for a self-signed certificate, for the controller and the runnersSee Gitea URL, Registration token and Self-signed certificates.
runtime
Section titled “runtime”The Docker-in-Docker backend. Exactly one of runtime and kubernetesRuntime must be set.
spec: runtime: image: gitea/runner:nightly-dind # a -dind variant, 5.3.0 or later; pin a version imagePullPolicy: IfNotPresent # Always, IfNotPresent or Never; the kubelet default when unset labels: # required, at least one, no default; runs-on name: docker://<job image>, or host ubuntu-latest: docker://docker.gitea.com/runner-images:ubuntu-latest envs: # environment variables of every job - name: NPM_CONFIG_REGISTRY value: "https://npm.example.com/" runnerEnv: [] # environment of the runner container, as a container's env; up to 256 runnerEnvFrom: [] # as a container's envFrom shutdownTimeout: 10m # how long a stopping runner waits for its job terminationGracePeriodSeconds: 900 # shutdownTimeout + 5m when unset runAsUser: 1000 # for -dind-rootless images, with storage.dockerStorageMountPath jobTmpfs: # job workspace and /tmp in memory workspaceSize: 8Gi # required tmpSize: 2Gi # optional; ignored with runnerConfigMapName pvcMounts: # existing claims in the namespace of the Runner - volumeName: shared-data # required claimName: my-existing-pvc # required mountPath: /mnt/shared # required, absolute readOnly: true # true by default configMapMounts: - volumeName: extra-config configMapName: runner-extra-config mountPath: /etc/runner-extra readOnly: true items: [] # optional, the keys to project defaultMode: 420 optional: false secretMounts: - volumeName: extra-secret secretName: runner-extra-secret # required mountPath: /etc/runner-secret readOnly: true items: [] defaultMode: 420 optional: false emptyDirMounts: # empty directories that init containers can fill - volumeName: prepared # required mountPath: /etc/prepared # required, absolute readOnly: true medium: "" # "" for the node's disk, or Memory sizeLimit: 64Mi # optional; the pod is evicted beyond it runnerInitContainers: # up to 16, run before the runner - name: prepare # required; not install-registration, chown-cache or runner image: "" # the runner image when empty imagePullPolicy: IfNotPresent # that of the runner image when image is empty command: ["sh", "-c", "..."] args: [] workingDir: "" env: [] envFrom: [] resources: {} # those of the runner container when unset securityContext: {} volumeMounts: # volumes of the four kinds of mounts above, by volumeName - name: prepared mountPath: /out runnerConfigMapName: "" # a ConfigMap with config.yaml, replacing the generated one- The
volumeNameof every mount must be unique, and not one of the names the controller uses, see Additional mounts. runnerEnvcannot setGITEA_INSTANCE_URL,CONFIG_FILE,RUNNER_STATE_FILE,GITEA_RUNNER_LABELSorGITEA_RUNNER_ONCE.- Label values cannot start with
kubernetes:, usekubernetesRuntimefor that.
kubernetesRuntime
Section titled “kubernetesRuntime”The Kubernetes backend. Cannot be combined with runtime.
spec: kubernetesRuntime: image: gitea/runner:nightly # not a -dind variant, 5.3.0 or later; pin a version imagePullPolicy: IfNotPresent capacity: 4 # jobs per runner pod, at least 1 labels: # required, 1 to 64 entries, no default; runs-on name: job image without a scheme ubuntu-latest: docker.gitea.com/runner-images:ubuntu-latest jobPodTemplate: {} # base of every job pod: metadata and spec only jobPodTemplates: {} # keyed by a label name, merged over jobPodTemplate; up to 64 runnerServiceAccountName: "" # the controller creates <name>-worker when empty runnerRunAsUser: 1000 # UID, GID and fsGroup of the runner pods, not 0 runnerResources: # resources of the runner container requests: cpu: 100m memory: 256Mi envs: [] # as in runtime runnerEnv: [] # as in runtime; also cannot set POD_IP runnerEnvFrom: [] shutdownTimeout: 3h # how long a stopping or draining runner waits for its jobs terminationGracePeriodSeconds: 11100 # shutdownTimeout + 5m when unset configMapMounts: [] # as in runtime secretMounts: [] emptyDirMounts: [] runnerInitContainers: [] # as in runtime, but must meet the restricted Pod Security Standard runnerConfigMapName: "" # labels in the form <name>:kubernetes://<image>- Label names are at most 255 characters, without
:,,or whitespace. Images cannot contain://. pvcMounts,runAsUserandjobTmpfsdo not exist with this backend.
scalability
Section titled “scalability”spec: scalability: minSize: 0 # runner pods kept when no job is waiting, 0 to 9999 maxSize: 10 # 1 to 9999, at least minSize cpuRequest: "2" # per runner pod (Docker-in-Docker) or job container (Kubernetes) memoryRequest: 4Gi cpuLimit: "4" # no limit when unset memoryLimit: 8Gi # no limit when unsetSee Scaling.
storage
Section titled “storage”spec: storage: className: standard # fallback StorageClass, and that of the cache server volume dockerStorageClassName: "" # Docker data root; className when empty actionCacheClassName: "" # action cache; className when empty cacheVolumeSize: 100Gi # Docker data root, per runner pod (Docker-in-Docker only) actionCacheVolumeSize: 10Gi # action cache, per runner pod cacheServerVolumeSize: 500Gi # built-in cache server dockerStorageMountPath: /var/lib/docker # the data root of the Docker daemon; change for rootless images cacheTTL: 168h # volumes are deleted this long after their last use cacheMaxAge: 720h # volumes of a runner pod are recreated this long after creation allowDeleteCachePVC: false # allow recreating volumes to change StorageClass or shrink them reclaimPolicy: Delete # Delete or Retain; that of the StorageClass when unsetdataVolumeSize is deprecated and ignored. See Storage and caching.
cacheServer
Section titled “cacheServer”The workflow cache is kept in one of three ways, and only one is in effect at a time:
- S3-compatible storage (recommended): set
s3. - An external cache server: set
externalServerURLandexternalSecretRef. - The built-in cache server: used when neither is set, adjusted with
hostandport.
s3 and externalServerURL cannot both be set, and the fields of the ways not in use are ignored.
spec: cacheServer: host: "" # built-in cache server: <name>-cache-server-svc.<namespace>.svc.cluster.local when empty port: 80 # built-in cache server: 80, or 8080 with kubernetesRuntime, where it must be 1024 or above externalServerURL: "" # use your own cache server instead of the built-in one externalSecretRef: # its key from a Secret name: cache-server-secret key: secret externalSecret: "" # deprecated: the key as plain text; not with externalSecretRef s3: # keep the cache in a bucket instead; not with externalServerURL endpoint: "https://s3.us-west-2.amazonaws.com" # required, http:// or https:// region: "us-west-2" # required bucket: "runner-cache" # required prefix: "" # <namespace>/<name> of the Runner when empty pathStyle: true # decided by the runner when unset accessKeyRef: # required name: runner-cache-s3 key: access-key secretKeyRef: # required name: runner-cache-s3 key: secret-keySee Workflow cache. With runnerConfigMapName the whole section is ignored.
Scheduling
Section titled “Scheduling”spec: nodeSelector: {} # runner pods affinity: {} # runner pods tolerations: [] # runner pods and the built-in cache server imagePullSecrets: [] # runner pods and the built-in cache server; not the job images of Docker-in-DockerWith the Kubernetes backend, job pods take theirs from kubernetesRuntime.jobPodTemplate. See Scheduling.
status
Section titled “status”| Field | Description |
|---|---|
targetSize |
The number of runner pods the controller currently aims for |
targetSizeUpdatedAt |
When targetSize last changed |