Skip to content
Try Gitea Cloud ☁️ for 30 days → Accelerate your Development & Deploys!
Support

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.registrationTokenSecretRef and gitea.registrationToken
  • One of runtime and kubernetesRuntime, with its labels

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 runners

See Gitea URL, Registration token and Self-signed certificates.

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 volumeName of every mount must be unique, and not one of the names the controller uses, see Additional mounts.
  • runnerEnv cannot set GITEA_INSTANCE_URL, CONFIG_FILE, RUNNER_STATE_FILE, GITEA_RUNNER_LABELS or GITEA_RUNNER_ONCE.
  • Label values cannot start with kubernetes:, use kubernetesRuntime for that.

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, runAsUser and jobTmpfs do not exist with this backend.
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 unset

See Scaling.

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 unset

dataVolumeSize is deprecated and ignored. See Storage and caching.

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 externalServerURL and externalSecretRef.
  • The built-in cache server: used when neither is set, adjusted with host and port.

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-key

See Workflow cache. With runnerConfigMapName the whole section is ignored.

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-Docker

With the Kubernetes backend, job pods take theirs from kubernetesRuntime.jobPodTemplate. See Scheduling.

Field Description
targetSize The number of runner pods the controller currently aims for
targetSizeUpdatedAt When targetSize last changed