Docker-in-Docker Backend
With the Docker-in-Docker backend, each runner pod runs the -dind variant of the runner image, which holds both the runner and a Docker daemon. Jobs run as containers of that daemon, as they do with a runner installed on a server, so workflows can use Docker freely: docker build, Docker actions, service containers with volumes. Each runner pod runs one job at a time.
A Runner uses this backend when spec.runtime is set. Exactly one of spec.runtime and spec.kubernetesRuntime must be set.
Cluster requirements
Section titled “Cluster requirements”The requirements below come on top of the general requirements and the storage requirements.
Privileged pods
Section titled “Privileged pods”The Docker daemon needs privileged containers, and this cannot be turned off. The rootless image does not lift the requirement either.
-
The namespace of the runner pods must allow privileged pods. With Pod Security Admission, set its level to
privileged:Terminal window kubectl label namespace <namespace> pod-security.kubernetes.io/enforce=privileged -
On OpenShift, grant the
privilegedSecurityContextConstraints to the default ServiceAccount of the namespace. -
Some hardened Kubernetes offerings forbid privileged containers altogether. Use the Kubernetes backend there.
In a namespace that does not allow them, the controller reports ApplyRunnerWorkerFailed warnings that mention violates PodSecurity, and Gitea lists the runners as offline until their pods can start.
Storage
Section titled “Storage”Each runner pod has two persistent volumes: the Docker data root, which keeps pulled images and layers, and the action cache. See Volumes of a runner pod.
The Docker data root volume must use block storage. Docker does not work on NFS, and jobs fail when its data root is on one. If block storage is scarce, keep only that volume on it:
storage: className: "<block storage class>" # fallback for the volumes below dockerStorageClassName: "<block storage class>" # Docker data root: must be block storage actionCacheClassName: "<any storage class>" # action cache: network storage worksCompute
Section titled “Compute”- Each runner pod requests 2 CPUs and 4Gi of memory by default (
scalability.cpuRequestandmemoryRequest), so the cluster needs nodes that fit one. - No limits are set by default, so a runner pod can use more than it requests. Compiling and building images inside jobs causes memory spikes: leave headroom on the nodes, or set
memoryLimit. - With job data in memory, raise the memory request and limit accordingly.
- Each runner pod attaches two volumes. Most platforms limit how many block volumes a node can attach, which caps the runner pods per node.
- Node autoscaling is not required. On a cluster of fixed size, set
maxSizeto what the nodes can hold: the runner pods beyond that stayPending.
Network
Section titled “Network”- The runner pods reach Gitea, the sources of the actions that jobs use (
https://github.comby default, see Actions), and the cache server or S3 bucket. - The Docker daemon in each runner pod pulls the job images, so the runner pods need access to those registries, and the nodes to the registry of the runner image.
- Job containers connect through their runner pod, so its egress also covers what jobs reach: Gitea at the URL it is configured with (its
ROOT_URL), and any package registries or services the workflows use. - With a default-deny NetworkPolicy, allow that egress. The controller creates no NetworkPolicy. The labels to select the pods with are listed in What the controller creates.
Checking the cluster
Section titled “Checking the cluster”This manifest checks that the StorageClass provisions volumes and that the namespace allows privileged pods. Replace <storage class> in it with the StorageClass the Runner will use: className is standard by default, not the default StorageClass of the cluster. When the volumes of the Runner use different StorageClasses, run the check once for each.
kubectl create namespace rc-preflightkubectl label namespace rc-preflight pod-security.kubernetes.io/enforce=privileged
cat <<'EOF' | kubectl -n rc-preflight apply -f -apiVersion: v1kind: PersistentVolumeClaimmetadata: name: preflightspec: accessModes: ["ReadWriteOnce"] resources: requests: storage: 1Gi storageClassName: <storage class> # the StorageClass to check---apiVersion: v1kind: Podmetadata: name: preflightspec: containers: - name: test image: busybox command: ["sh", "-c", "touch /data/ok && sleep 3600"] securityContext: privileged: true volumeMounts: - name: data mountPath: /data volumes: - name: data persistentVolumeClaim: claimName: preflightEOF
kubectl -n rc-preflight wait --for=condition=Ready pod/preflight --timeout=3mThe check passes when the output says condition met: the pod runs, so the volume was provisioned and mounted, and the namespace accepts privileged pods. If it times out, kubectl -n rc-preflight describe pod preflight shows why. Clean up with kubectl delete namespace rc-preflight.
Creating a Runner
Section titled “Creating a Runner”Create the namespace and a Secret with the registration token:
kubectl create namespace gitea-runnerskubectl label namespace gitea-runners pod-security.kubernetes.io/enforce=privilegedkubectl -n gitea-runners create secret generic runner-registration-token \ --from-literal=token=<registration token>Save the following as runner.yaml, replacing the Gitea URL and the StorageClasses:
apiVersion: gitea.com/v1kind: Runnermetadata: name: my-runner namespace: gitea-runnersspec: gitea: instanceUrl: "https://<gitea host>" registrationTokenSecretRef: name: runner-registration-token key: token
runtime: image: gitea/runner:6.0.0-dind # a -dind variant labels: # runs-on name: job image ubuntu-latest: docker://docker.gitea.com/runner-images:ubuntu-latest ubuntu-24.04: docker://docker.gitea.com/runner-images:ubuntu-24.04
scalability: minSize: 1 # runner pods kept when no job is waiting maxSize: 10 cpuRequest: "2" memoryRequest: 4Gi
storage: # sizes for a trial className: "<storage class>" # action cache and cache server dockerStorageClassName: "<block storage class>" # Docker data root: block storage cacheVolumeSize: 30Gi # Docker data root, 100Gi by default actionCacheVolumeSize: 5Gi # action cache, 10Gi by default cacheServerVolumeSize: 20Gi # built-in cache server, 500Gi by defaultdockerStorageClassName is the StorageClass of the Docker data root, which holds the images that jobs pull and the data they write, such as their workspaces. Use fast block storage for it: Docker does not work on NFS, and jobs read and write this volume heavily. In this example, the action cache and the volume of the built-in cache server use className. Without dockerStorageClassName, the Docker data root uses className too, so if one StorageClass of block storage suits all volumes, set className only. See Storage.
The volume sizes suit a trial. For production, size them as described in Capacity planning, and keeping the cache in S3-compatible storage is recommended.
kubectl apply -f runner.yamlkubectl -n gitea-runners get runner,pod,pvcWith minSize: 1, a runner pod my-runner-0001 starts next to a my-runner-cache-server pod, usually within a few minutes, and a runner of the same name comes online in the runner list of Gitea, on the page the token comes from. kubectl -n gitea-runners describe runner my-runner shows the progress: RegisterRunner and Create... events on success, warnings otherwise, see Troubleshooting.
To see the runners scale, add a workflow that uses one of the labels, as .gitea/workflows/runner-check.yaml, to a repository that the token covers and that has Actions enabled:
name: Runner checkon: [push]jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: cat /etc/os-releaseAll other options are described in Configuration and Storage and caching, and listed in the reference. The rest of this page covers the options of this backend only.
Runner image
Section titled “Runner image”runtime: image: gitea/runner:6.0.0-dind- Use a
-dindvariant. The image of the same version without the suffix has no Docker daemon, and jobs fail. - Use runner 5.3.0 or later. 6.0.0 or later is recommended.
- Pin a version in production. The default,
gitea/runner:nightly-dind, changes every day. - If an image does not work with the controller, the controller reports
RunnerRegisteredItselforRunnerNotOnlineevents, see Troubleshooting.
Private job images
Section titled “Private job images”With this backend, images are pulled in two places:
- The node of the runner pod pulls the images of the pod itself: the runner image and those of init containers. It uses
spec.imagePullSecretsof theRunner, see Scheduling. - The Docker daemon in the runner pod pulls the job images. It is not part of Kubernetes, and does not use
spec.imagePullSecrets.
Give the runner the credentials for the job images as a Docker configuration file instead, from a Secret of type kubernetes.io/dockerconfigjson:
runtime: secretMounts: - volumeName: docker-config secretName: <registry credentials> mountPath: /etc/docker-config readOnly: true items: - key: .dockerconfigjson path: config.json runnerEnv: - name: DOCKER_CONFIG value: /etc/docker-config- The runner uses these credentials for every image it pulls for a job: the job image, the images of services, and those of Docker actions and
docker://steps, including the base images of Docker actions built from a Dockerfile. - Workflows can instead give the credentials themselves, in the
credentialsofcontainerandservices, which take precedence over those of the runner. If only a few workflows use private images, this needs no change to theRunner. These credentials, however, are used only for theimageofcontainerand ofservices, not for the job images that labels point to or the images of Docker actions. The job fails when these credentials are empty. - Images that job steps pull themselves, with
docker pull,docker build,docker composeor tools such as Testcontainers, do not use these credentials, as the steps run the Docker client of the job container. Log in to the registry in the workflow instead, for example withdocker login.
Shutdown timeout
Section titled “Shutdown timeout”When a runner pod is deleted while it runs a job, for example when a node is reclaimed or maxSize is lowered, the runner waits for the job to finish:
runtime: shutdownTimeout: 10m # 10m by default # terminationGracePeriodSeconds: 900 # shutdownTimeout + 5m by defaultshutdownTimeoutis how long the runner waits for the running job, after which the job is cancelled. Raise it if jobs can take longer than 10 minutes.terminationGracePeriodSecondsis how long Kubernetes waits before it kills the pod. Do not set it belowshutdownTimeout, or the pod is terminated before the job is done. The controller reports aGracePeriodTooSmallwarning when it is.
Configuration changes do not cut jobs short: a runner pod that runs a job is only rebuilt after the job, see How configuration changes are applied.
Keeping job data in memory
Section titled “Keeping job data in memory”The data a job writes, such as the checked out code and the build output, goes to the Docker data root volume. Jobs bound by disk I/O, for example ones that handle many small files, can keep it in memory (tmpfs) instead:
runtime: jobTmpfs: workspaceSize: 8Gi # the job workspace tmpSize: 2Gi # optional: /tmp in the job containerscalability: memoryRequest: 14Gi # must include the tmpfs, see below memoryLimit: 16Gi| Field | Required | Description |
|---|---|---|
workspaceSize |
Yes | The most the job workspace can hold. The workspace is deleted when the job ends, which frees the memory. Pulled images stay on the Docker data root volume. |
tmpSize |
No | The size of /tmp in the job container. Docker actions (runs.using: docker) each have a /tmp of the same size. Ignored with runnerConfigMapName. |
- A runner pod runs one job at a time, so size them for the peak use of one job. A job that writes more fails with
no space left on device. - It works with the rootless image. Jobs that run on the host do not use it.
The tmpfs counts against the memory of the runner pod, and the controller does not raise memoryRequest and memoryLimit for it:
memoryRequest ≥ memory of the job + workspaceSize + tmpSizememoryLimit ≥ memory of the job + workspaceSize + tmpSize × 2tmpSize counts twice in the limit, as a Docker action has its own /tmp of that size. With the values above and a job that needs 4Gi, the request is at least 14Gi and the limit at least 16Gi. A request too low lets the node overcommit its memory. A limit too low causes the job to be terminated for exceeding its memory limit once the tmpfs fills up, instead of failing with no space left on device. The controller reports a JobTmpfsMemoryTooSmall warning when the memory settings clearly cannot hold the tmpfs.
Running jobs as a non-root user
Section titled “Running jobs as a non-root user”The -dind-rootless variants run Docker, and the jobs, as a non-root user. They need both of these settings:
runtime: image: gitea/runner:6.0.0-dind-rootless runAsUser: 1000storage: dockerStorageMountPath: /home/rootless/.local/share/docker- Without
runAsUser, the controller does not hand the Docker data root volume over to that user, and Docker fails to start. - Without
dockerStorageMountPath, the volume is mounted where the rootless daemon does not look. No error occurs at first, but pulled images are lost whenever the pod is recreated, and they accumulate on the node’s disk until it is full.
The runner pods stay privileged: Docker needs kernel privileges to create network namespaces and mount file systems, regardless of the user it runs as. The benefit of the rootless image is that job code does not run as root, which remains a worthwhile defense-in-depth measure when CI runs untrusted code, although doing so is strongly discouraged.
Mounting existing volumes
Section titled “Mounting existing volumes”pvcMounts mounts existing PersistentVolumeClaims into the runner pods, for jobs that read or write shared data:
runtime: pvcMounts: - volumeName: shared-data claimName: my-existing-pvc # in the namespace of the Runner, not created by the controller mountPath: /mnt/shared readOnly: true # true by defaultThe runner only lets job containers mount the paths listed in container.valid_volumes of the runner configuration. The controller adds each mountPath, and the paths below it, to that list, so job containers can mount them:
jobs: example: runs-on: ubuntu-latest container: image: docker.gitea.com/runner-images:ubuntu-latest volumes: - /mnt/shared:/data steps: - run: ls /dataWith your own runner configuration, list the paths in its container.valid_volumes yourself. A claim that more than one runner pod mounts at once needs an access mode that allows it, such as ReadOnlyMany or ReadWriteMany.