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

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.

The requirements below come on top of the general requirements and the storage requirements.

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 privileged SecurityContextConstraints 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.

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 works
  • Each runner pod requests 2 CPUs and 4Gi of memory by default (scalability.cpuRequest and memoryRequest), 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 maxSize to what the nodes can hold: the runner pods beyond that stay Pending.
  • The runner pods reach Gitea, the sources of the actions that jobs use (https://github.com by 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.

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.

Terminal window
kubectl create namespace rc-preflight
kubectl label namespace rc-preflight pod-security.kubernetes.io/enforce=privileged
cat <<'EOF' | kubectl -n rc-preflight apply -f -
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: preflight
spec:
accessModes: ["ReadWriteOnce"]
resources:
requests:
storage: 1Gi
storageClassName: <storage class> # the StorageClass to check
---
apiVersion: v1
kind: Pod
metadata:
name: preflight
spec:
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: preflight
EOF
kubectl -n rc-preflight wait --for=condition=Ready pod/preflight --timeout=3m

The 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.

Create the namespace and a Secret with the registration token:

Terminal window
kubectl create namespace gitea-runners
kubectl label namespace gitea-runners pod-security.kubernetes.io/enforce=privileged
kubectl -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/v1
kind: Runner
metadata:
name: my-runner
namespace: gitea-runners
spec:
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 default

dockerStorageClassName 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.

Terminal window
kubectl apply -f runner.yaml
kubectl -n gitea-runners get runner,pod,pvc

With 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 check
on: [push]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: cat /etc/os-release

All 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.

runtime:
image: gitea/runner:6.0.0-dind
  • Use a -dind variant. 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 RunnerRegisteredItself or RunnerNotOnline events, see Troubleshooting.

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.imagePullSecrets of the Runner, 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 credentials of container and services, which take precedence over those of the runner. If only a few workflows use private images, this needs no change to the Runner. These credentials, however, are used only for the image of container and of services, 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 compose or 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 with docker login.

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 default
  • shutdownTimeout is 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.
  • terminationGracePeriodSeconds is how long Kubernetes waits before it kills the pod. Do not set it below shutdownTimeout, or the pod is terminated before the job is done. The controller reports a GracePeriodTooSmall warning 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.

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 container
scalability:
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 + tmpSize
memoryLimit ≥ memory of the job + workspaceSize + tmpSize × 2

tmpSize 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.

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: 1000
storage:
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.

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 default

The 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 /data

With 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.